Contrived workflow - Specifics

Modern technical writing - Andrew Etter 2016

Contrived workflow
Specifics

This section provides an end-to-end, functional example that conforms to all of my guidelines, with a few detours to make it more realistic.

1. You get hired at a software company. Congratulations!

2. Three weeks (or months) later, you are wise and knowledgeable about the company's products and users. You also have your health insurance all sorted out.

3. You create four different files in GitHub Flavored Markdown: about.md, tutorial.md, concepts.md, and process.md.

4. You install Sphinx with pip install sphinx.

5. You create a directory structure and Sphinx configuration file (conf.py) by running sphinx-quickstart.

6. You try to build these Markdown files into a help system with Sphinx, but Sphinx uses reStructuredText, not Markdown. You curse several times.

7. You use Pandoc to convert the files from Markdown to reStructuredText, but after examining the resultant files, you decide you hate RST and would rather continue to write in Markdown.

8. No problem, you create a script that converts all of your Markdown files to RST and then builds with Sphinx. This way, you can write in Markdown, but still take advantage of Sphinx. The script looks something like this:

9. find . -name \*.md -type f -exec pandoc -f markdown_github -t

10. rst -o {}.rst {} \;

sphinx-build -b html ./source ./build

11. The script works, but you still need to build a TOC tree (table of contents) for Sphinx. You create a file called index.rst and embed the converted content from about.md within that file so that you have to write as little RST as possible. index.rst looks like this:

12. .. toctree::

13. :maxdepth: 1

14.

15. tutorial

16. concepts

17. process

18.

.. include:: about.rst

19. Everything looks pretty good, so you create a new repository on GitHub, clone the empty repository to your computer, and add your documentation to it.

20. When you commit your files, you notice that you need to edit .gitignore to ignore build (the built help system) and *.rst (the converted RST files) except index.rst. .gitignore looks like this:

21. build/

22. source/*.rst

!source/index.rst

23. You realize that anyone who views the repository on GitHub will have no idea what it is, how to build it, or how to contribute to it, so you add README.md to the repository root.

24. You decide that the default Sphinx theme stinks, so you download a new one and point conf.py at it. Then you decide that one stinks, too, and take the time to learn how to build your own.

25. Once you're happy with how everything looks, you harass your IT department until they give you the subdomain docs.yourcompany.com. When they ask what sort of server you need and what you need installed, you tell them that you built a static website and just need a directory for file transfers. They're super impressed10.

26. You transfer the finished help system to docs.yourcompany.com and are officially a published writer.

27. Three days later, some developers approach you about a change to the documentation. You tell them you're busy and that they should submit a pull request. They too are super impressed11.

28. Promotions and financial windfalls ensue.