In-tree Markdown documentation for Chromium OS

[Daniel Erat]

I've added a new public Chromium OS documentation repository where Markdown-formatted files can be checked in. It's patterned after Chromium's top-level docs/ directory.

After the manifest changes land, you should see it show up as a top-level "docs" directory the next time you sync your checkout. If you've had your checkout for a while, repo may give you an error like this:

GitError: --force-sync not enabled; cannot overwrite a local work tree. If you're comfortable with the possibility of losing the work tree's git metadata, use `repo sync --force-sync docs` to proceed.

Sorry about that. :-( We checked out a different repository to the same place in the past, and repo errors out instead of just moving the old repository away. Either running "repo sync --force-sync docs" as instructed or manually moving away your old .repo/projects/docs.git directory should clear it up.

The new repository is pretty empty right now, but I encourage you to help change that! Chromium seems to be in the process of moving away from Google Sites to in-tree Markdown (I think). Checked-in documentation has some advantages over dev.chromium.org:

- External contributors can make and upload changes.

- You get to use your preferred text editor instead of fiddling around to convince a WYSIWYG editor to put text inside/outside of the preceding link/bold/italic span.

- You can upload proposed changes for someone else to review (although as with Chromium's docs, feel free to TBR uncontroversial changes).

- You can check in documentation alongside your code.

- All documentation is formatted identically (no more weirdo docs using 11-point dark blue Verdana).

I've linked to Chromium's documentation guidelines and best practices in the top-level README.md file. Chromium OS's situation is a bit different since we have a zillion repositories instead of one main one. If your code is self-contained, I think it's reasonable to have documentation live alongside it (perhaps in your own docs/ subdirectory). I envision the new top-level repository as being most useful for more-widely-applicable docs -- think best practices or build instructions, for example. I'd like to know what others think, though.

[Daniel Erat]

If you get "this operation must be run in a work tree" errors from "repo sync", try the same fixes as last time.

Specifically, I think you need to nuke everything that's returned when you run "find .repo/project* -name docs\*" in the top of your checkout and then run "repo sync --force-sync" again.

[Mike Frysinger]

the downside that Chromium hasn't been able to address and applies to us too is that searchability goes way way down.  with dev.c.o, you have one site you can go to and stuff things into a text box.  now i have to search multiple locations.

i agree that docs/ should be a "fallback" of sorts -- if you're writing docs for a specific project, the best place for that to live is most likely right alongside the code in the same repo.

a note on the md_browser: it can be pretty finicky currently when you try to browse it, so try giving it paths directly if it craps out.  e.g. i ended up doing:

  ./chromium/src/tools/md_browser/md_browser.py -d $PWD

then browsing to http://localhost:8080/src/third_party/daisydog/README.md directly

its rendered output does not match great with gitiles.  i've sent some CLs to improve both though, so hopefully this should be a short lived issue.

-mike

--
--
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

[Daniel Erat]

The searchability point is a good one. I don't think that the results that I get from e.g. http://dev.chromium.org/system/app/pages/search?scope=search-site&q=d-bus are particularly good, either.

For the power manager documentation at http://dev.chromium.org/chromium-os/packages/power_manager, I'm planning to move things over to src/platform2/power_manager/docs and then just make the d.c.o page point there (perhaps along with adding an overview page in /docs that mentions where the power management code is). I think we'll always have an initial discoverability problem when people don't know where the code implementing a particular aspect of the system lives, but I think that that's an easier problem to solve.

I'll ask around to see if there are any plans on the Chromium side to make it easier to search for Markdown documentation (apart from using "git grep" or code search tools).