Thoughts on modern, scalable, and remote-first enterprise-level technical documentation systems. Practical examples that merge together Technical Writing and DevOps.

See my LinkedIn page for more information on what I do professionally or to contact me.

David Image
  • Automating CHANGELOGs via enforced commit message conventions

    Maintaining CHANGELOGs for engineering documentation is a challenge. Ensuring a clear commit message convention reduces complexity and improves functionality.

  • One-click templating

    Using Jinja and Cookiecutter to instantly create documents in your company's style and configuration.

  • Automating style checks

    A scalable solution to enhance our documentation quality across large and distributed authoring teams.

  • Source data to customer content flow

    Using python to extract data from engineering systems, clean it, then parse it for user documentation.

  • Protecting content

    How we can realistically protect content whilst ensuring usability?

  • Multi-variant documents

    One document that shares content with several outputs. You could use this method where you have a single product with customer specific content blocks. Or your product is mostly similar with another product.

  • Integrating an external DMS into pipeline

    You may be required to archive documents in a specific DMS system.

  • Documentation and Information Architecture

    A synthesized list of key tasks related to structuring and maintaining an enterprise-level documentation management system.

  • DevOps for documentation

    Automatically testing and deploying documentation using a CI/CD pipeline

  • Automatically building drafts

    Using a CI/CD pipeline and Git to produce timestamped draft PDFs and DOCX files

  • Readability analysis

    Quickly cleaning text and generating a readability score

  • Converting documentation

    Using common tools, we can quickly convert .docx or .tex files to .rst

  • Documentation workflow

    A graphic showing the key steps in a docs-as-code workflow approach.

  • Change request workflow

    A simple and auditable change request workflow that incorporates merge request approvers.

  • Version control

    Using Git as a tool to version control documentation gives us complete transparency and control over content updates.

  • Organizational level content analysis

    We can use Regex to identify stylistic errors or asses the impact of content changes.

  • My docs-as-code toolchain

    I use a set of open-source and well document tools to create and manage documentation at an organizational level.

  • Change request management

    Using GitLab as a document lifecycle tool gives us strong collaboration and change request functionality.

  • Analyzing document changes

    We can use git-diff or a document lifecycle tool to analyze changes between any document versions.

  • Applying structured data

    Using controlled templates to write DITA and Schema.org compliant content helps us write more functionally.

  • Applying a Docs-as-Code approach to QMS

    Creating documentation correctly in the first instance removes the need for secondary Quality Management Systems (QMS) or Document Management System (DMS) software. Integrating Gitlab as a DevOps tool for documentation is a lightweight and scalable way to enhance a QMS.

  • Developing documentation remotely

    With the COVID-19 virus pandemic changing the way companies apply work from home policies, a Docs-as-Code approach to documentation facilitates remote collaboration on a larger scale.

  • Creating technical documents

    General information on using Sphinx or Pandoc to create scalable technical documentation using Docs-as-Code principles.