Authoring Workflows

Before answering some questions it might help everyone understand the workflows this project enables and how we can use it to collaboratively author content for our readthedocs site.

Content Sources

The plan is to have maintainers of the RTD site manage the directory hierarchy and documents through Google Drive and author content through Google Docs for semi-technical project information. Developers of projects author content through the GitHub Wiki for more technical project specific information.

We broke down how to author content into separate guides depending on whether you use Google Docs or the GitHub Wiki:

Removing the Confusion

Some confusion starts to occur though, when considering existing Markdown documents authored through the GitHub Wikis. The same confusion occurred with how to handle the restructuredText documents in this project.

RestructureText Documents

All the restructuredText documents, minus the ones like index.rst which are absolutely required will be replaced by Google Docs documents. This way there will be no need to manually maintain any restructuredText documents at all. The present content for some of them can easily be relocated to Google Docs and we can let the script just link them into the TOC in an automated fashion.

Existing Committed GitHub Wiki Markdown Documents

RestructuredText is rarely used. There's not many and we will easily convert them to be Google Docs documents. The Markdown documents will keep being authored through the GitHub Wiki. They're automatically committed to the Git repository dedicated to the project's wiki. Developers and the community are very used to this mechanism of authoring content. Plus technical GitHub users have a tendency to view project specific technical documentation on the Wiki of the project if not straight in Readme.md files.

The GitHub Wiki is based on the Gollum Wiki. It is poorly suited to manage content in a hierarchy. Even if you put Markdown documents into a file hierarchy they are all presented as flat documents in the Wiki. Meaning the Wiki does not present your documents in the file structure used in the Git backing store. You have to use the _Sidebar.md file to create a menu to represent any organization to the documents. We can easily generate this _Sidebar.md file based on the directory hierarchy. However, when creating a new GitHub Wiki document, through the GitHub interface there's really no way to specify where that document will be dropped. It will be put at the root of the git repository used for the wiki. So there's no point to organizing things based on some directory structure.

We chose to use a non-visual embedded element in the Markdown, a comment, to contain a parameter for the parent path of the document. This is not in the directory structure but in terms of the _Sidebar menu structure and the document's position in the RTD TOC tree.

A GitHub pre/post commit hook, or build task can handle extracting the parent path and enact changes to the RTD TOC tree and rewrite the _Sidebar. Without the parent path parameter, the Markdown file is put into an uncategorized menu parent. If that's not what is optimal or intended, then the job of categorizing it is left up to others managing the documentation. The parameter can be used like so and must be the first comment in the document with the key starting on a new line:

<!-- 
PARENT_PATH: /Guide
ORIGIN: github
-->

Frequently Asked Questions

There have been several questions about how this all works. Some of the questions raised:

Where are all the dot.md files? I can only see docx files.

This all depends where you are in the hierarchy. The Markdown files usually come from GitHub Wiki pages in project wikis. These wikis are backed by their own git repository. (Talk about eating your own dog food 👍) These repositories are added submodules attached under the Projects folder.

The files pulled in from Google Docs are docx files. These will predominantly be found everywhere other than under the Projects directory.

NOTE: At the present time no docx files dropped into or below Projects will be converted or integrated into the RTD site.

Can I check out the dot.rst files and commit them back directly to Github, or should I instead change the files on Google Drive, convert to Markdown and sync from there?

Way back, Mike kicked ass and whipped up an RTD site for us using restructuredText. We still have some of these docs in the repository, however they're old and need to be removed. The idea here is to not use restructuredText and stick to just Google Docs or GitHub Wiki pages.

So what do we do with the restructuredText documents?

These should be converted to Google Docs and we can generate the restructuredText from them. They will need to be edited and maintained overtime. So it makes sense to use gdocs for that since its much easier for writers.

And another part I'm still trying to figure out is the Projects dir. Are those links to wikis in GitHub projects? Will then RTD import the contents of the wiki pages, or only link to them on GitHub?

First questions answer is YES. It will import them. There's a specific reason for that which needs to be made clear in case someone whats to change this in the future. We're not going to readthedocs because of the pretty site it generates. Even the unified single documentation site is somewhat ancillary since we can link to docs in wikis too. The main reason is to have all our docs searchable from one place.

Conclusions

This approach makes it so we can all author technical and non-technical documents for the overall unified RTD document for the organization using our preferred mechanism through Google Docs and the GitHub Wiki. Checkouts with manual editing of Markdown files are also supported.