Modern technical writing - Andrew Etter 2016
Script your complexity away
Specifics
If you go against my advice and decide to create and distribute PDFs, you might have to create a so-called publishing pipeline. Publishing pipelines are the steps through which lightweight markup files become print-ready documents. All lightweight markup languages build to HTML, but the journey to PDF often requires an extra step—hence the pipeline. You probably have to build to LaTeX first, then LaTeX to PDF. LaTeX installers are massive 1.8 — 2.5 GB downloads, so if you use a set of machines to build your documentation, consider using just one as the PDF machine.
Pandoc is a marvelous tool for converting between markup formats. It calls itself the Swiss Army knife of markup converters and can convert to and from a huge number of formats. Unfortunately, these conversions are rarely perfect. If one day you decide that you'd rather write in AsciiDoc instead of Markdown, expect to perform some manual cleanup after running the conversion script.
For simplicity, Pandoc conceals the LaTeX step, which makes the creation of PDFs pretty straightforward:
pandoc your-document.md -f markdown_github -o your-document.pdf
Note
You can even convert to the Microsoft Word document format by specifying .docx instead of .pdf.
Unfortunately, this method only works if all of your content is in a single file—unlikely. More likely is that you'll need to do something like this:
pandoc title.txt 1.md 2.md 3.md 4.md -f markdown_github -o your-document.pdf
Note
If you want to customize the way the PDF looks, doing so requires a new LaTeX template and is extremely complex. If customization is important, consider using a tool like wkhtmltopdf or PhantomJS so that you can use CSS instead of LaTeX for styling. Whatever you do, don't compromise the look of your HTML in order to have more attractive PDFs. Everything you do should be geared towards more useful, accessible websites.
You still want HTML, though, so you should include a second build command in the same script:
jekyll build --source source --destination build/html
You might need to check out several remote repositories before building, rename or move files, or run a supplemental script. The point is that your lightweight markup files should be as simple as possible. Don't require people to conform to silly guidelines in their writing (or worse, write in XML) just so your build script is a little easier to understand. If any part of the technical writing process should be complicated, this is it. You might need to read a book on Windows PowerShell, Bash, Rake, or Grunt.
1. Lightweight markup goes in (simple).
2. A script checks out a Git repository, applies a custom theme, compiles LESS files to CSS, converts Markdown files to AsciiDoc, and finally runs the build commands (complex).
3. A static website comes out (simple).
Commit the build script to the documentation repository and use README.md to explain what it does and which dependencies it has. In this case, I might list Pandoc and Jekyll as dependencies and provide links to their installation documentation.
If you use Rsync, you probably don't want to include it in your build script. Making a separate "publish" script that calls Rsync gives you the opportunity to manually verify that the help system opens and functions properly before you send it to a remote server. This final, ten-second sanity check is worthwhile.