We electronically control revisions for this topic and deploy it directly online. Any copies you generate from the latest revision are uncontrolled. Ensure you refer to the latest revision online when possible.
Latest revision: /docs-as-code//2020/03/16/creating-technical-documents.html
General information on using Sphinx or Pandoc to create scalable technical documentation using Docs-as-Code principles.
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 text in a what-you-see-is-what-you-get (wysiwug) manner is a key principle of a scalable Docs-as-Code approach.
Sphinx is a great tool for developing complex technical documentation. It provides strong variable control, single-sourcing, multiple outputs - anything you’d expect from a technical documentation tool out-of-the-box.
One key difference from more traditional technical authoring tools is that you can layer python functions over top of it. 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 is the responsibility of engineering. Improving content quality and reducing errors in transcribing or copy / pasting.
Pandoc is a tool for developing 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 are 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.
demo.docs-as-code.com (via Sphinx, download PDF from within online environment)
How to tile a kitchen backsplash (via Jekyll for html output, download Pandoc PDF from within)
Print this page to generate a local PDF.