Improved collaboration for Chromium development documentation

[Nicholas Bishop]

Is there any interest in moving the Chromium development documentation
to a more collaborative model? Something simple like markdown pages in
a git repository, rendered on readthedocs.org.

Right now chromium.org contains a huge amount of useful information,
but it's not always well organized or up to date. And as far as I know
changes have to be submitted by pinging the dev list like the "Typos
in wiki pages" email sent earlier today. Having a simple way to
contribute changes via git would certainly be an improvement, both for
increasing documentation contributions and improving review of the
documentation.

Does this sound reasonable? Is anything like this already being worked
on? I'd be happy to help get things started or contribute to an
existing effort.

Thanks,
-Nicholas

[Zachary Reizner]

I like the idea of switching to markdown. In my experience of editing some chromium os docs, the WYSIWYG editor makes it really hard to get the formatting consistent and gets in the way of writing clean documentation.

--
--
Chromium OS Developers mailing list: chromiu...@chromium.org
View archives, change email options, or unsubscribe:
http://groups.google.com/a/chromium.org/group/chromium-os-dev?hl=en

To unsubscribe from this group and stop receiving emails from it, send an email to chromium-os-dev+unsubscribe@chromium.org.

[David]

I like this idea. There are some frustrating bits of the current documentation where you can't get to where you need to. (Namely on the portage build faq page in the section titled "How do I check that my package is present on the download mirror" where it says upload it 'manually to localmirror')

It should be more of a living document as opposed to one that is statically built. Its strange that at the top of the portage build faq it has said: "TODO: Needs an introduction that someone who's a bit more of a newbie can understand" for more than a year or two.

All e-mail correspondence to and from this address is subject to the North Carolina Public Records Law, which may result in monitoring and disclosure to third parties, including law enforcement.

[Marc Herbert]

On Wednesday, 25 March 2015 09:51:27 UTC-7, Nicholas Bishop wrote:

Is there any interest in moving the Chromium development documentation
to a more collaborative model? Something simple like markdown pages in
a git repository, rendered on readthedocs.org.

Oh yes.

+1 for opening the documentation to external submissions. Less jumping back and forth between: 1. internal and up-to-date docs;  2. public and obsolete.

+1 for markdown (WYSIWYG is so messy)

Note: there are collaborative models which are implemented with WYSIWYG, think... Google docs for instance. Changing the model is IMHO much more important than the technology - but I'd take both.

[Gaurav Shah]

We have indeed been thinking about this switching away from sites and moving to hosted versioned documentation built from source. It's more a question of setting up the infrastructure and docs pipeline. For the documentation format, the current plan is to use the following:

1) Doxygen (inline documentation for C/C++)

2) Sphinx (inline documentation for Python, and standalone docs).

[Nicholas Bishop]

That sounds great. What can I do to help?

> To unsubscribe from this group and stop receiving emails from it, send an

> email to chromium-os-d...@chromium.org.

[Robert Iannucci]

(FWIW, gitiles now renders markdown natively. All of the git-on-borg documentation is now hosted through gitiles: https://gerrit-internal.git.corp.google.com/docs/+/master/users/index.md)

> email to chromium-os-dev+unsubscribe@chromium.org.

[Robert Iannucci]

(here's the spec sheet: https://gerrit-internal.git.corp.google.com/docs/+/master/users/markdown.md)

[Robert Iannucci]

Here's an external example of gitiles serving it's own documentation. README.md automatically gets promoted to the default view, https://gerrit.googlesource.com/gitiles/, and browsing directly to the document renders it full-screen: https://gerrit.googlesource.com/gitiles/+/978fe8e37481e83c145c152729d94bf4dcc56296/README.md

[Robert Iannucci]

And here's the external markdown specsheet: https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md

[Marc Herbert]

Bumping up this old thread.

Part of our internal documentation is specific to either our lab or infrastructure or hardware,... generally of no interest to anyone but us. The rest on the other hand is either amending or extending (or duplicating...) the public guides. While the extra effort caused by this split is relatively small for us, the inability to submit new or updated documentation is a bigger loss for the Chrome OS project and community.

An interesting coincidence is the shutdown of Google code as a product. As a consequence there seems to be a number of migration options available, for instance: https://code.google.com/p/support-tools/wiki/WikiToMarkdownTool .

Is there any access to the source of the https://www.chromium.org/chromium-os/developer-guide wiki pages? IANAL but the license seems permissive enough for re-use.

Marc

[Marc Herbert]

Just found Chromium has already migrated:

  https://code.google.com/p/chromium/wiki/00README

  https://chromium.googlesource.com/chromium/src/+/master/docs/

Not ChromiumOS? Or did I miss something?

Marc

[Mike Frysinger]

it depends on the content.  Chromium keeps some narrow/directed content in the repo that it's relevant to, but still uses dev.chromium.org heavily.  there are no plans currently to get rid of the Google Sites usage.  same goes for Chromium OS really.

as for earlier posts in this thread (like Gaurav's), those plans have been scuttled.

-mike

--

[Mike Frysinger]

there is no way for non @chromium.org people to view the source of pages on the wiki.  but @chromium.org isn't restricted to Googlers ...

i agree that the inability to post CLs/updates to the dev.chromium.org site is a bad experience.

-mike

--