Edit documentation with Google Docs

When authoring a new standard documentation page, or extensively editing an existing page, using Google Docs makes it easier to collaborate on content.

Once new or updated content is agreed in Google Docs it needs to be converted to Markdown before creating a pull request to update the standard documentation.

Set up your editing environment

  1. Open the Docs to Markdown page

  2. Click Install

  3. Create a document in a subfolder of 0. Standard Development in Google Drive.

    Note

    Documentation outside the Reference section of the documentation should be filed in Iterative Improvements.

  4. If you are editing an existing page, copy the content from the body of the HTML page and paste it into your document:

    ../../_images/googledocs.png

Create or update content in Google Docs

Write or edit your documentation page, adhering to the Style guides and the following conventions:

  • Set the page title to Heading 1.

  • Do not skip heading levels.

  • Do not add empty lines before/after headings.

  • Do not add empty lines between list items.

  • Do not indent text, unless the text is a quotation.

  • Do not underline text. Use headings, bold, or italics.

Convert a Google Doc to Markdown

  1. Open the document to convert in Google Docs. If the document was open when you installed the extension, re-open the document.

  2. Click the Extensions > Docs to Markdown > Convert menu item

  3. Click the Markdown button

  4. Copy-paste the output into a Markdown file

Tidy Markdown before creating a pull request

  1. Read, then remove, the top comment

  2. Regex-replace \n\n\n+ with \n\n, because the document might have extra newlines

  3. Replace HTML tags (regex-search <\w), as appropriate

  4. Check all links, and replace internal links (regex-search \]\()

  5. Check heading levels (regex-search for ^#), because the heading levels in the document might have been incorrect

  6. Check whitespace and punctuation around bold (**), emphasis (_) and linked (\[ and \]) text, because whitespace or punctuation might have been styled or linked

  7. Check blockquote text, because all indented text in the document is interpreted as blockquote text, but this might not be your intention