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 text in a what-you-see-is-what-you-get (wysiwug) manner is a key principle of a scalable Docs-as-Code approach. ## Sphinx 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 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](https://demo.docs-as-code.com) (via Sphinx, download PDF from within online environment) [How to tile a kitchen backsplash](/2020/03/15/how-to-tile-a-kitchen-backsplash.html) (via Jekyll for html output, download Pandoc PDF from within) Print this page to generate a local PDF.
1 minute read | Concept

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 text in a what-you-see-is-what-you-get (wysiwug) manner is a key principle of a scalable Docs-as-Code approach.

Sphinx

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

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.

Example

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.

See also

Home | Contact