Hello
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.