Documentation Engineering a.k.a. Reliable Up-To-Date Docs

[g-pavlov]

Documentation Engineering

Summary

This project approaches the problem of documentation development by approximating it to the problems in source code development and addressing it with software and process engineering. It provides a high level of automation and software support, comparable to the one in a best practice, complex end-to-end development processes, particularly in OSS projects.

In a nutshell it:

• fuses the documentation process into the software development process
• utilises the same process automation infrastructure - CICD, containers, bots, automatic PR checks
• supports separation of concerns between documentation providers (domain experts creating content) and documentation publishers (experts in design and delivery of documentation content)
• frees capacity for creative work, automating procedural tasks in the documentation process from development of material to publishing it on a publishing channel
• supports complex, multicomponent projects spread across multiple repositories that have established end-to-end processes

Motivation

Documentation development and delivery is traditionally seen as a separate domain that eventually has cross points with software in the production process. But paradigm shifts in software engineering like agile processes and design thinking bring closer the previously distinct roles in the process and they start to exchange and adopt process models and tools in a more unified approach. That is particularly visible in open source projects, where dynamism and collaboration but also the "do-more-with-less" approach are survival factors. These are some reasons why we see a new paradigm at documentation development called documentation-as-code making its way more and more and particularly in open source and especially in complex projects.

Often this approach is described as keeping your documentation close to code and using the same tools as developers to work on it. While this is true there is a lot between the lines here. Considering that this means having a docs folder with markdowns in your repo and using git to check in and out and pull requests to collaborate over changes is a good start, but it is almost certainly an oversimplification of the potential of the documentation-as-code paradigm. It wouldn't bring significant benefits to a complex projects with CICD-orchestrated automatic processes, consisting of multiple repositories, each being a component that needs documentation, like Gardener or Kubernetes for example. In fact most claims for implementation of documentation-as-a-code in OSS projects that we see stop short at the tool support in the initial development material phase on a per repo basis. When documentation material moves close to code for good, and there are multiple repositories to consider, we face a distinct issue. How the documentation content from multiple repositories can be aggregated in a consistent, publishable documentation bundle and qualify it. And then how to release and deploy documentation with software releases, considering product and component versions.

Applying the documentation-as-code paradigm implies a high degree of automation and software support, comparable to the one in a development process, which is a software engineering problem. In fact, the documentation development process resembles significantly the software development process in that way. Coming from this angle, this project addresses the documentation process problems with software engineering means not only focusing on the initial phase of documentation development but all the way along the whole process down to a delivery on a publishing channel.

Proposal

The proposal is to define the practices and deliver the software necessary to support a documentation process that shares the same infrastructure as software development process for multicomponent, multi-repository, GitHub-based projects, that can be used to deliver documentation on multiple publish channels from the same source.

Formally such documentation process can look like this:

Or if we apply this concept to the delivery of documentation by the Gardener OSS project:

Material Contribution

A documentation material contribution, being new material or existing one pulled for update, is the usual GitHub-driven process with change commits, collaboration and reviews until a final agreement, known from contributing code.

Developing documentation on this stage can be supported by local editor, containerized build and preview of changes, or the same provided by an online CMS, such as netlify CMS. Running the same build as CICD and previewing changes as they will be seen by end users on a publish channel, or at least the documentation bundle that will be transformed for that, introduces a transparency that significantly reduces the turntime for a change.

Introducing formal enforcement of guidelines such as markdown formatter, or early and formal quality check, including dead links, spelling and expression checks is a significant improvement reducing review times and removing the burden of trivial checks.

Finally, merging documentation changes to a repository is subject to automatic formal checks that guard the quality of the contributed material. These are mostly the same quality checks that are available to be run while developing material.

Build

Building a documentation bundle has several stages. The common one is the initial - aggregating source content into a desired structure. The next build stages depend on the purpose of the bundle and the publishing technology and may require technology-specific transformation. Therefore they can be customized as needed for the specific use-case.

Building starts from a manifest file that describes the desired documentation bundle and its structure. It is convenient to manage this file in a repository dedicated to documentation or a root component of the project.

The product of the build is a documentation bundle publishable on a particular platform.

Continuous Integration and Continuous Deploy (CICD)

Projects that have CICD setup to orchestrate change management will have the documentation reusing it for coherent release and deploy cycles. When a documentation change is merge a CICD job is triggered to build the documentation bundle and run quality checks. Upon release the build result, that is the documentation bundle and source are added to the release artifacts. Continuous deploy uses those artifacts to publish them on a target publish channel.

There can be more than one publishing channel and normally that will require also different documentation bundle possibly structured precisely for that channel and optionally built for a specific publishing platform. Publishing on each channel can be performed by dedicated CICD pipelines.

Summary of topics

The project supports documentation development process similar to software development contributing software support in the following directions:

• Material change contribution
  • Sandboxed build
  • Change Previews
  • Quality and compliance control
  • Pull requests quality control Automated Quality Control gardener-attic/docs-toolbelt#8
• Build documentation bundle Build Documentation Source into Bundle docforge#23
  • Pull documentation sources from multiple locations and storage system types (incl. GitHub and file system) as instructed by a documentation bundle manifest
  • Reconcile linked resources in documents - download as appropriate and rewrite links Preserving Pulled Documents Consistency docforge#7
  • Applying automatic processing on source documents, including for a particular build system (e.g. Hugo) Documentation Source Processors docforge#20
• CICD integration guidelines

Validation Scenarios

OSS project

The scenario validates the extremely popular among OSS project process organization with GitHub-based dev process, CICD integration, build with Hugo, publish on GitHub Pages. The project to validate it will be Gardener and the expected result is versioned documentation bundles published at https://gardener.cloud upon Gardener release.

Internal project

The scenario validates the versatility of the concept and the implementation in a different environment and process. For example, publishing documentation in a DITA system. A stakeholder with more concrete scenario is to be defined.

Definition of DONE

• Validation scenarios accomplished
• Documented
  Documentation for adopters, and developers
• Tested
  75%+ avg code coverage with tests, integration tests
• Stable
  The project concepts and core implementations are stable enough to adopt and extend with new tools in the given scope without significant changes.
  • 1+ more alternative(s) to a supplied solution in the scope

[Kristian-ZH]

most of the things are already done.
Others are not anymore in the backlog