About this guide¶

A docs-as-code workflow makes it easy to publish documentation on a static website. Markdown is a markup language you use to write documentation in text files, which you then store in a Git repository. Hosted Git services such as GitLab or GitHub, together with tooling such as Visual Studio Code, make it easy to maintain and host documentation.

Adopting a docs-as-code workflow transforms documentation from a chore into an engineering process. By treating your written content with the same rigour as code, you enable a collaborative approach to documentation.

This site is the full setup, authoring, customisation, and testing guide for prodockit-template and other Zensical projects built on the prodockit package. It's hosted independently of any individual fork of those templates, so it can be kept current without every existing fork being stuck with whatever it looked like the day it was forked.

The docs-as-code philosophy¶

Docs-as-code means using the same tools and workflows for documentation as you do for software development. This creates a unified environment where writers and developers use the same tools and development workflow.

Markdown as the Source of Truth

Markdown is a lightweight markup language that's simple to read in its raw form and consistently renders on the web. You write your documentation in it, then convert that documentation into HTML for web publishing.

Version control via Git

Storing files in a Git repository (such as GitHub, GitLab, or Bitbucket) enables the tracking of all changes to the documentation. There will be a complete history of "who changed what and why," making it easy to undo errors and audit changes.

Collaborative Reviews

Instead of emailing Word docs back and forth, teams use Pull Requests (PRs) or Merge Requests (MRs). This enables peer reviews, automated linting, and transparent discussions before any content goes live.

The docs-as-code stack¶

To move from using a word processor or simple website to a scalable and effective documentation tool set needs a stack of tools, as shown in the diagram below. The stack is made up of three layers: the authoring tool, the docs-as-code builder, and the code repository and management system.

Authoring tool

Effective documentation depends on tools that help with content editing and automate quality checks, including spelling, grammar, style and formatting consistency. While there are numerous text editors available, VS Code stands out as a favoured option due to its extensive ecosystem of extensions. By using Visual Studio Code, writers can take advantage of a variety of extensions that offer real-time quality assurance. Some of the extensions available for VS Code include spell checkers, grammar checkers, and linters that enforce style guides. These tools help ensure that the documentation is clear, consistent, and professional. We are suggest using Python, Zensical Studio, Even better TOML and LTeX+.

Docs-as-code builder

Markdown files can serve as a foundation for a static website. However, they often need enhanced formatting options through additional themes and styling. A docs-as-code builder then transforms the Markdown and supplementary instructions into HTML, applying a theme to generate a professional-looking website. Zensical is a fast and reliable docs-as-code builder that processes Markdown files and creates a static documentation website. It lets you view the website locally before publishing, so you can confirm the final output meets your quality standards. Additional extensions, such as the prodockit package, can be added to Zensical to provide extra features like heading numbering, a references page and a pdf document with an index.

Code Repository and Management

By connecting directly to a Git repository, this integrated environment establishes a secure, centralised vault that tracks the history of project files. It records each modification as a distinct commit, letting users audit changes or revert to earlier versions if errors arise. Before finalising any work, a pull request triggers a peer-review process, where collaborators comment on, test, and approve the updates. This workflow ensures that only vetted, high-quality content reaches final publication. GitLab and GitHub are popular platforms that provide these capabilities, along with additional features like issue tracking, project management, and continuous integration.

Docs-as-code in production¶

As a student, you'll follow a simplified workflow, since you won't be handling documentation that spans thousands of pages and needs a large development team to maintain it. Nevertheless, understanding the approach used at scale can help you appreciate the value of the skills you'll develop. GitLab provides a video that outlines the entire process for their documentation and highlights the importance of the skills you gain through a docs-as-code methodology.

Zensical for docs-as-code¶

Zensical provides the themes and tools necessary to draft professional documentation in Markdown with instant local previews. Once finalised, you can publish your site by uploading the files to a Git repository. From there, automated pipelines build and deploy the content into a live website.

Zensical, written for speed and reliability using the Rust programming language and Python, publishes documentation as a website.

We have provided an additional extension, the prodockit package, which adds extra features to Zensical enabling you to create a professional-looking documentation website, together with a PDF version of the report.

prodockit-template is a documentation template built on Zensical and prodockit, available for you to fork and clone into a project that you can use to write your own document or report.

Guide structure¶

This guide continues by presenting the following sections, in the order you'll need them for the development of your documentation.

Install tooling

The Install tooling section describes how to install the core prerequisite tools and create a fork of the document template. By the end of this section you will have an environment ready to develop your own professional or academic documentation. The instructions are available for macOS, Windows 11, and Ubuntu/Debian Linux.

Start editing

The Start editing section describes how to edit the documentation and view the changes locally before publishing to a Git repository. It also describes how to synchronise your changes with the Git repository.

Markdown basics

The Markdown basics section describes the principles of Markdown and how to use it to write your documentation.

Zensical basics

The Zensical basics section describes the principles of Zensical and how to use it to create and manage your documentation - the same general-purpose features available on any Zensical site.

Customisation

The Customisation section discusses how to configure prodockit-template to give it a different style and layout to meet your specific needs - features macros.py and the prodockit package add on top of Zensical (heading numbering, the references page pattern, Surrey/generic branding, and more) that don't exist in a stock Zensical project.

Additional tooling

The Additional tooling section describes additional tools you can install to help you create quality docs-as-code documents. They will take additional effort to install and configure.

Shell commands

The Shell commands section describes the shell commands used in this guide. It's intended as a reference for you to use when writing your own documentation.

Continue to the next section to get started with the installation of the core tools and creating a fork of prodockit-template.