Unified Documentation

The Mess

It's really important to list where we are, so we can see, where we need to go with our documentation.

How does the community "comfortably" authors docs today?

• Google Docs Usually for nontechnical to semi-technical documentation and excellent for collaboration but not so great for organizing it into a table of contents for publication.
• GitHub Wiki Mostly technical documentation snippets like a faq, or howto on a specific project technical aspect.

What are the existing silos of docs across the organization?

• Google Docs
• GitHub Wiki
• Website HTML

What are the different kinds of documentation in a project?

• Non-Technical Product Documentation (may go semi-technical) Descriptions, ideas, concepts, explanations of the products of the project at the highest level, and an introduction for as wide an audience as possible.
• Semi-Technical User Materials Quick start product user guides, how-to guides, and explanations of things like the P2P cloud economy. How to engage and get going.
• Technical Documentation Power user HowTos, FAQs, and developer documentation on specific subproject components of products.

Organization and Structure

Markdown in the GitHub Wiki, and Google Docs both have weak support for organizing project documentation. Sure in a single document you can organize things but across documents and sections of a website they're not adequate tools. Other tools have emerged like ReadTheDocs to address these problems which generates a searchable website with an organized table of contents and tree. Readthedocs also hosts your project's documentation at docs. so we would have docs.subutai.io generated and hosted with a proper organization.

ReadTheDocs does not organize your documentation, it is just a tool to help us do that. So we're going to have to figure it out. What's the best structure? If our organization and structure is messy, the tool will produce a mess. Let's get this right by modeling how we want our documentation to be organized hierarchically to facilitate and consider:

• totally new users, and
• how to feed users more knowledge slowly about the products, and
• what information they need in the natural progression to delve deeper without overwhelming them, and
• separating the concerns of different kinds of people in the audience
  • non-technical viewers and perspective users
  • semi-technical users
  • highly-technical IT and developer types

The best thing to do is just start working on a table of contents and have the community agree on it. Here's a good starting point. When done we can publish and maintain it here in the index.rst or in some intermediate form which is easier to edit and is used to generate the index.rst.

Docs Project Structure

Luckily for us Mike already started. How he found the time is beyond me. Anyways there's a read the docs installation that was created before, I just moved it here and massaged a few things:

• RTDs CommonMark Support Added (to render GitHub Wiki Markdown)
• Added the GitHub Project Wiki Repositories as Git SubModules Under projects Folder
• Added a Vagrantfile for easy to use infrastructure to constantly auto build the RTD Website (served on port 8000 on VM)
• Added some content but that's a work in progress ...

Aims

• Reference Google Docs in TOC Tree to be included into RTD site build, after export as Markdown
• Reference GitHub Wiki Markdown Documents in TOC Tree to render in RTD site build
• Create a convention to tag Google Docs, and GitHub Wiki Markdown docs to automate inclusion in RTD TOC Tree
• Automate everything so management overheads are extremely minimal
  • Edit Google Docs and it changes automatically incorporate into RTD
  • Edit GitHub Wiki Docs and it changes automatically incorporate into RTD
  • If problems arise and the automation fails we are immediately notified

How to get there?

To get to the ultimate vision we need to:

• Define and use conventions on organizing and tagging documentation in GitHub Wiki and Google Docs
• Research access API for Google Docs and write a script:
  • that is aware of our conventions above
  • downloads the Markdown exports from Google Docs
  • adds them to TOC Tree of RTD
• Research how to generate GitHub Wiki Sidebar and TOC for Project Organization in GitHub:
  • script must generate these materials so project wiki docs look organized in GitHub
  • script must use conventions (tags) to add Markdown pages to the RTD TOC tree

Research Notes

Looking around for things that can help us.

• Chrome Plugin to Export Google Docs as Markdown Not useful for this project perhaps because it is just a Chrome Plugin
• gdocs2md This is useful, and it's a Google Docs script. Need to check if it works and play with it. Here's a nice article with directions on how you can use this script with a Google Docs document. A how to video for using it.
• ABANDONED gdoc-mardown-converter Also a GDocs script but converts and adds documents to the G-Drive. This is was nice: shit don't work see issue 2
• Google Drive CLI Client for Linux G-Drive CLI client that allows us to pull down the G-Drive documentation root directory and overlay it into the docs directory. Nice article on how to use this.
• Google Marketplace Markdown Export Add-On
• Adding Sidebar, Header and Footer to GitHub Wiki
• Automatically Generate Sidebar Scripts

Conventions

We talked about using some conventions to enable the automated inclusion of documents into the RTD TOC Tree using scripts. We discuss these here in this section.

Google Docs

The best thing to do is setup a shared folder in Google Drive as the root of the hierarchy of documents. We will use the folder hierarchy to present cues on how to build the TOC. The folder structure should match the documentation TOC defined. This is a start.

Need to figure out how document tags will play a role here if at all.

GitHub Wiki

Things are already deep down in the TOC since project Wiki folders are deep down. I think we simply need to organize things with tags or a directory structure for FAQs, HOWTOs, User and Developer Guides.

TODO add this stuff!