Creating technical documents
General information on using Sphinx or Pandoc to create scalable technical documentation using Docs-as-Code principles.
Background
Using text based documentation tools lets us layer other functions such as GitLab or Pandas over top of our documentation. Incorporating this approach of using plain text manner persists as a key principle of a scalable Docs-as-Code approach.
Sphinx
A great tool for developing complex technical documentation. It provides strong variable control, single-sourcing, variable outputs - anything you'd expect from a technical documentation tool out-of-the-box.
The ability to layer python functions over the top document generation ensures as a key difference from more traditional technical authoring tools. For example, pulling information directly from an engineering system in your organisation and parsing it directly into its documentation. This means that the source and reliability of the content remains the responsibility of engineering. Improving content quality and reducing errors in transcribing or copy / pasting.
Pandoc
Use Pandoc to develop smaller, one-off type PDF copies of structured web content such as this topic.
Commonly, manufacturing companies may have an online internal knowledge base of information, yet remain required to print and attach simple work instructions or health and safety information to machinery. This content must meet strict ISO type content control requirements, yet remain functional for users. example: | demo.docs-as-code.com (via Sphinx, download PDF from within online environment)
How to tile a kitchen back splash (via Jekyll for HTML output, download Pandoc PDF from within)
Print this page to generate a local PDF.