Authoring on Google Docs

These are directions for those using Google Docs to author content for the searchable RTD website generate by this project. Perhaps the most important thing we can say to you:

Garbage in garbage out!

There's nothing Google Docs, RTD, or this project can do for stupidity, laziness, carelessness, and just a disregard for following directions and doing things properly. We can't help cosmonauts in their own universe either! We all need to get with the program and be alert. Y'all know what I mean.

Google Drive: `readthedocs`

The shared Google Drive folder named readthedocs is the root of the file and document hierarchy. Underneath there you will find directories and files used to generate the RTD website. The directory structure is used to generate the table of contents for the RTD website. The structure looks like so:

Products
- Peer
- Bazaar
- Router
Projects
Community
Resources

The Projects area for now is banned. Don't put anything in there. Presently only the Markdown files from the wiki are processed in that folder. Maybe we'll add the ability to use Google Docs to add documentation there but it gets sync'd to the GitHub Wikis of the projects and requires special consideration to avoid conflicts. We'll deal with that but later. Some other general rules to follow:

DO NOT put PDF files in there!
DO NOT put WORD or ODT files that were produced in MS Word or Open Office there! Author docs in G-Docs from scratch!
DO NOT enable folder sync on your desktop computer!
DO NOT author partial content there, transfer it from somewhere else after you're done done!

The last item is important but presently we have no choice for testing. However the good news is we have not automated site deployment so you are still safe until we do. Once we have automated deployment putting a doc in will generate and deploy it to the documentation website. The system and auto deployment will make life easier, but it also makes it easier to shoot yourself in the foot.

Please take this seriously until we have some reliable controls in place. Keep asking in the #documentation room about the automation status. We will NOT enable automated site deployment until we are all confident on the initial content. Then we need to change the work. There are some ideas around having a readthedocs_dev folder, but that's in the future.

Document Structure

The information here will change. Check the updates section at the end of this document for more clarification. We will try to edit this section to inline those changes but might just quickly add an update block.

Document Names

WARNING: NO SPACES IN DOCUMENT NAMES, USE UNDERSCORES _ INSTEAD

The names you use for the documents created under the readthedocs folder are used to derive the document's title. The title is generated by replacing underscores with spaces, then capitalizing the first letter of every word. These titles are used in the RTD LHS table of contents menu (TOC).

Document Ordering

QUESTION: I'm writing guides for the products under the Products directory in Google Drive and the order of the files is important? How can I control the ordering of documents in the Peer, Router, or Bazaar directories?

Document ordering in the TOC also affects the RTD next and prev buttons on the bottom of each page. These are nice features for implementing guides with a specific flow.

You can control ordering by prefixing a number followed by an underscore to documents to position them in the TOC. The number will be ignored when generating the title of the document in the TOC. For example a GDoc named 1_foo will be order before a GDoc named 2_bar in the same folder. Their titles will be Foo and Bar in the TOC. When documents are not index prefixed, they're added at the end in alphanumeric sorting order.

Document Headings and Title

If there is no H1 header (that's a title in Google Docs), the name of the file will be used as the H1 header and injected automatically. The left hand side table of contents will use the file name, spaces replacing either

Everything depends on proper document structure. Always use proper headings in your Google Docs. DO NOT increase the font, and make the text bold! We're relaxing the absolute adherence to structure to make it so you don't have to learn restructureText (ooh the irony in the name). However that means you need to seriously adhere to headings.

Testing

Until we enable automated deployment, you can author content directly in the readthedocs directory. After auto deployment we have to have a transitioning scheme to prevent deploying content that is not ready. Keep up to date with the #documentation room to track this status.

So author your content in the readthedocs directory. Use the Vagrantfile and VM to generate content. See Using the Vagrant VM. You can generate the full RTD site and navigate to your pages to check how they look.