[PSA] Wiki documentation is being migrated off of code.google.com

[Andrew Bonventre]

The problem:

• code.google.com is being shut down (or, at least, set to read-only).

• Chromium (https://code.google.com/p/chromium/w/list) as well as many related projects have documentation that lives on the wiki (this covers the main chromium project to start).

• There are 136 documents that need to find a new home.

• A lot of the information is out of date or no longer relevant.

• Changes to the documentation are not audited or reviewed.

The goal is to start simple and allow for changes to be made without much friction down the road.

We will replace the wiki with a smaller, more focused set of documentation written in Markdown that lives within the source. Markdown has become the standard for hosted SCM (GitHub, BitBucket, etc.), a very simple syntax, and a wide variety of tooling built for it. Examples of this already happening are within the gyp and gn subprojects (https://chromium.googlesource.com/chromium/src/+/master/tools/gn/docs/).

The goal is to have a much smaller subset of high-quality content checked in so that it’s much easier to manage.

We will use the findings during this process to determine how to approach improving the documentation on the Sites page (dev.chromium.org) as well as migrating the wiki content of other projects.

Implementation Details:

• A set of guidelines and best practices will be released to ensure quality and consistency across the documentation. They will live in src/docs.

• A tool to render pages in your local checkout that mirrors Gitiles will be released to ease the editor workflow.

• For the sake of initial simplicity, a top-level src/docs/ directory will contain all Markdown documentation files. Documentation for chromium can only live in src/docs/. Standalone tools like gn get their own docs/ directories. After the migration, this restriction will most likely get relaxed. The only exception is that any directory in the source can contain a README.md file that describes the contents of that directory. Knowing what to put in a readme vs docs/ will be covered in the best-practice documents described above.

• Migration

• Placeholder wiki pages (“this page has moved to <foo>”) will not be migrated.

• All wiki pages will be converted to Markdown using (https://code.google.com/p/support-tools/wiki/WikiToMarkdownTool), renamed to be underscore_case to be in line with Chromium style (links to pages will be fixed as well), limited to 80 cols, and submitted for review to be added to src/docs/.

• This thread will be updated with review.

• Community members will have the opportunity to

• Obsolete the page and commenting on the review saying it should be deleted.

• Suggesting changes within the review.

• A timeline of a two business days will be given before the change is landed.

• Once the content on the wiki has been migrated, a single page will remain indicating that it has moved to the source.

• Any new documentation that would be placed in the wiki should be landed in the source (excluding in-process design docs, OKRs, meeting notes, etc. Those should live in Sites or Google Docs).

The following issues are being considered, but not as blockers for this migration:

• Searching the docs will begin as a crude UI using codesearch or Google, but will need to be improved. https://chrome-infra-docsearch.appspot.com will be renamed to cr-docs.appspot.com and expanded to crawl chromium/related projects as well.

• The structure of the documentation will most likely go through some reorganization. To start, though, we are taking a simple approach with all of it living within top-level directories.

• Tooling within codereview.chromium.org needs to be improved to allow for in-page preview for CLs.

• A longer edit cycle will result from the need to do code reviews. However, the new workflow allows for updates to documentation to happen alongside code changes. This makes it easy to keep code and documentation in sync.

Why not just move everything to the Sites page?

dev.chromium.org has its own staleness problem with ~1200 pages and much more content that is out of date. This migration is a first step toward having all documentation be in a simple, portable, and well-supported format that sits next to the source.

Thanks,

andybons

[Michael Hablich]

When are you going to start with this? I am eager to know what your experience is afterwards because V8 also needs to migrate its Wiki.

[Benjamin]

+1

Is there a roadmap?

在 2015年8月20日星期四 UTC+8上午4:47:56，Andrew Bonventre写道：

[Julie Parent]

+andybons, who got dropped somehow.

He has started on it already, but I'll let him provide more clear timeline.

[Andrew Bonventre]

While things are happening out of order (for instance, the Markdown files are not in line with Chromium’s style guide yet), the initial import review is up — https://codereview.chromium.org/1309473002/

PLEASE GLANCE IT OVER AND COMMENT WHETHER ANY PAGES SHOULD BE DELETED.

The less pages we have, the more maintainable it is.

Regarding timelines for other projects, Chromium has by far the largest number of wiki pages to bring over. The process for other projects will consist of:

+ Prune

+ Convert

+ Send Review

+ Land

The timeline is continuous, and we will move to other chromium-related projects as we complete each one. You can help by deleting wiki pages that should not be brought over.

[Andrew Bonventre]

UPDATE: The documents have been migrated to abide by Google’s style guide and the guide has been open-sourced here: https://github.com/google/styleguide/tree/gh-pages/docguide

As a result, Chromium's wiki will be going read-only on Monday, September 7th (one week from today). Please do not add or edit any content there. Submit your changes to src/docs/ 

The OWNERS file is very permissive (*) and so changes can be made by anyone and approved by any committer. We ask that you follow the style guide and be patient if Nodir and I perform drive-by reviews to ensure this.

Thanks,

A

[Nico Weber]

It seems like the documentation isn't indexed by google.com. I used to be able to search for "chromium $topic" and the wiki page I wanted was always in the top 3 hits. Now none of our documentation ever shows up in search results. Is that on your radar?

--
--
Chromium Developers mailing list: chromi...@chromium.org
View archives, change email options, or unsubscribe:
http://groups.google.com/a/chromium.org/group/chromium-dev

[Julie Parent]

This isn't (well, wasn't) on my radar.

Andy, Nodir?

[Andrew Bonventre]

This has been filed internally as http://b/23076814

[Nico Weber]

On Thu, Nov 5, 2015 at 7:57 AM, Andrew Bonventre <andy...@chromium.org> wrote:

This has been filed internally as http://b/23076814

Looks like that hasn't seen any changes except for some activity right after it was filed. Are there any workarounds for this until that bug gets fixed? This is breaking several of my workflows. (For example, when updating clang I used to search for "chromium roll clang" to find the list of bots I need to send tryjobs for, but now that doesn't find the docs page I'm looking for.)

[Primiano Tucci]

Revving up this thread with an extra question: is there an established pattern for dealing with images / screenshots in mardkdown docs?

+ruuda@ and I are in the process of moving some tracing pages from the chromium.org site to markdown. Lot of those pages have screenshots though, how are we supposed to deal with that?

The options I see are:

- check in the images in the repo (whatever/docs/images). Gitiles markdown supports referring to them with a limit of 256 K (which is a good incentive to prevent people to check-in multi MB images). On the other side I'm not a huge fan of checking binary files in the codebase.

- upload images in a publicly accessible google drive folder, and then use the Drive API endpoint https://drive.google.com/uc?export=view&id=$FILE_ID (e.g., https://drive.google.com/uc?export=view&id=0B3KuDeqD-lVJVVFFOVdpb0tJV0U). But this makes the edit workflow a bit more complicated (upload, get the file id) and error prone (if you forget public ACLs).

- Any other options (?)

Opinions?

[PhistucK]

Perhaps use a Google Storage bucket for the images with a simple web user interface for uploading them?

This will keep the images versioned, so getting documentation from a certain revision will always show the corresponding images for that revision of the documentation.

☆PhistucK

You received this message because you are subscribed to the Google Groups "Chromium-dev" group.

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

[Primiano Tucci]

On Mon, Jan 18, 2016 at 11:45 AM PhistucK <phis...@gmail.com> wrote:

Perhaps use a Google Storage bucket for the images with a simple web user interface for uploading them?

This will keep the images versioned, so getting documentation from a certain revision will always show the corresponding images for that revision of the documentation.

Yeah now that I think to that it's not a terrible idea. We could reuse the upload_to_google_storage logic with some tweaks.

I imagine we could have a upload_markdown_image which under the hoods does:

 - invoke upload_to_google_storage, ensuring the right mimetype is passed and setting up the proper Cache-Control: public headers

 - output the corresponding markdown code that can be copy-pasted.

The edit workflow feels pretty smooth in my mind. If there is consesus for this I'm up to fire a cl to create such a script. I'd just need somebody (+infra-dev) to create a bucket with the right ACLs.

WDYT?

[Andrew Bonventre]

I’d file a bug with the Infra tag to allow for proper triage. That should get the right people looking at this idea.

[Primiano Tucci]

Done http://crbug.com/579117

[Michael Giuffrida]

On Wednesday, August 19, 2015 at 1:47:56 PM UTC-7, Andrew Bonventre wrote:

The problem:

• code.google.com is being shut down (or, at least, set to read-only).

• Chromium (https://code.google.com/p/chromium/w/list) as well as many related projects have documentation that lives on the wiki (this covers the main chromium project to start).

• There are 136 documents that need to find a new home.

• A lot of the information is out of date or no longer relevant.

• Changes to the documentation are not audited or reviewed.

The goal is to start simple and allow for changes to be made without much friction down the road.

We will replace the wiki with a smaller, more focused set of documentation written in Markdown that lives within the source. Markdown has become the standard for hosted SCM (GitHub, BitBucket, etc.), a very simple syntax, and a wide variety of tooling built for it. Examples of this already happening are within the gyp and gn subprojects (https://chromium.googlesource.com/chromium/src/+/master/tools/gn/docs/).

The goal is to have a much smaller subset of high-quality content checked in so that it’s much easier to manage.

We will use the findings during this process to determine how to approach improving the documentation on the Sites page (dev.chromium.org) as well as migrating the wiki content of other projects.

Implementation Details:

• A set of guidelines and best practices will be released to ensure quality and consistency across the documentation. They will live in src/docs.

Has this happened? I only see docs/documentation_best_practices.md which is just a copy of the public Google guide.

 

• A tool to render pages in your local checkout that mirrors Gitiles will be released to ease the editor workflow.

• For the sake of initial simplicity, a top-level src/docs/ directory will contain all Markdown documentation files. Documentation for chromium can only live in src/docs/. Standalone tools like gn get their own docs/ directories. After the migration, this restriction will most likely get relaxed. The only exception is that any directory in the source can contain a README.md file that describes the contents of that directory. Knowing what to put in a readme vs docs/ will be covered in the best-practice documents described above.

As the componentization effort progresses, now is a good time to reconsider whether all Chromium docs should live in the top-level src/docs/ directory. One README.md may not be enough to document an entire component, and having documentation in two places (README.md + the code, and a src/docs/my_component/ directory) isn't ideal. OTOH, having all docs in one place makes things easier, especially when a particular component spans multiple top-level Chromium directories. 

[Nico Weber]

On Mon, Feb 13, 2017 at 5:59 PM, Michael Giuffrida <mich...@chromium.org> wrote:

On Wednesday, August 19, 2015 at 1:47:56 PM UTC-7, Andrew Bonventre wrote:

The problem:

• code.google.com is being shut down (or, at least, set to read-only).

• Chromium (https://code.google.com/p/chromium/w/list) as well as many related projects have documentation that lives on the wiki (this covers the main chromium project to start).

• There are 136 documents that need to find a new home.

• A lot of the information is out of date or no longer relevant.

• Changes to the documentation are not audited or reviewed.

The goal is to start simple and allow for changes to be made without much friction down the road.

We will replace the wiki with a smaller, more focused set of documentation written in Markdown that lives within the source. Markdown has become the standard for hosted SCM (GitHub, BitBucket, etc.), a very simple syntax, and a wide variety of tooling built for it. Examples of this already happening are within the gyp and gn subprojects (https://chromium.googlesource.com/chromium/src/+/master/tools/gn/docs/).

The goal is to have a much smaller subset of high-quality content checked in so that it’s much easier to manage.

We will use the findings during this process to determine how to approach improving the documentation on the Sites page (dev.chromium.org) as well as migrating the wiki content of other projects.

Implementation Details:

• A set of guidelines and best practices will be released to ensure quality and consistency across the documentation. They will live in src/docs.

Has this happened? I only see docs/documentation_best_practices.md which is just a copy of the public Google guide.

robertshield & co just published https://chromium.googlesource.com/chromium/src/+/master/docs/documentation_guidelines.md (after you sent your mail; I figured it's good to mention it on this thread too for posterity).

 

 

• A tool to render pages in your local checkout that mirrors Gitiles will be released to ease the editor workflow.

• For the sake of initial simplicity, a top-level src/docs/ directory will contain all Markdown documentation files. Documentation for chromium can only live in src/docs/. Standalone tools like gn get their own docs/ directories. After the migration, this restriction will most likely get relaxed. The only exception is that any directory in the source can contain a README.md file that describes the contents of that directory. Knowing what to put in a readme vs docs/ will be covered in the best-practice documents described above.

As the componentization effort progresses, now is a good time to reconsider whether all Chromium docs should live in the top-level src/docs/ directory. One README.md may not be enough to document an entire component, and having documentation in two places (README.md + the code, and a src/docs/my_component/ directory) isn't ideal. OTOH, having all docs in one place makes things easier, especially when a particular component spans multiple top-level Chromium directories. 

This is already somewhat widely not being honored. It looks like the emerging convention is to have a "docs/" folder in your component: https://cs.chromium.org/search/?q=file:docs%5C/.*%5C.md$+-file:third_party+package:%5Echromium$+-file:src/docs+-file:native_client+-file:v8&type=cs

Rob, should your guide mention where docs should go? It mentions a README.md at the root of the component, but if a component needs more docs than that?

 

• Migration

• Placeholder wiki pages (“this page has moved to <foo>”) will not be migrated.

• All wiki pages will be converted to Markdown using (https://code.google.com/p/support-tools/wiki/WikiToMarkdownTool), renamed to be underscore_case to be in line with Chromium style (links to pages will be fixed as well), limited to 80 cols, and submitted for review to be added to src/docs/.

• This thread will be updated with review.

• Community members will have the opportunity to

• Obsolete the page and commenting on the review saying it should be deleted.

• Suggesting changes within the review.

• A timeline of a two business days will be given before the change is landed.

• Once the content on the wiki has been migrated, a single page will remain indicating that it has moved to the source.

• Any new documentation that would be placed in the wiki should be landed in the source (excluding in-process design docs, OKRs, meeting notes, etc. Those should live in Sites or Google Docs).

The following issues are being considered, but not as blockers for this migration:

• Searching the docs will begin as a crude UI using codesearch or Google, but will need to be improved. https://chrome-infra-docsearch.appspot.com will be renamed to cr-docs.appspot.com and expanded to crawl chromium/related projects as well.

• The structure of the documentation will most likely go through some reorganization. To start, though, we are taking a simple approach with all of it living within top-level directories.

• Tooling within codereview.chromium.org needs to be improved to allow for in-page preview for CLs.

• A longer edit cycle will result from the need to do code reviews. However, the new workflow allows for updates to documentation to happen alongside code changes. This makes it easy to keep code and documentation in sync.

Why not just move everything to the Sites page?

dev.chromium.org has its own staleness problem with ~1200 pages and much more content that is out of date. This migration is a first step toward having all documentation be in a simple, portable, and well-supported format that sits next to the source.

Thanks,

andybons

--