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¶
Open the Docs to Markdown page
Click Install
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.
If you are editing an existing page, copy the content from the body of the HTML page and paste it into your document:
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¶
Open the document to convert in Google Docs. If the document was open when you installed the extension, re-open the document.
Click the Extensions > Docs to Markdown > Convert menu item
Click the Markdown button
Copy-paste the output into a Markdown file
Tidy Markdown before creating a pull request¶
Read, then remove, the top comment
Regex-replace
\n\n\n+
with\n\n
, because the document might have extra newlinesReplace HTML tags (regex-search
<\w
), as appropriateCheck all links, and replace internal links (regex-search
\]\(
)Check heading levels (regex-search for
^#
), because the heading levels in the document might have been incorrectCheck whitespace and punctuation around bold (
**
), emphasis (_)
and linked (\[
and\]
) text, because whitespace or punctuation might have been styled or linkedCheck blockquote text, because all indented text in the document is interpreted as blockquote text, but this might not be your intention