Security problem

Up to date technical documentation might not be the obvious candidate for a security topic, but it is. Good documentation will contain up-to-date diagrams and application designs. Furthermore, it will warn users about potential pitfalls when using product or integrating with it.

Maintaining up to date technical documentation is cumbersome task and not very popular among developers. For this reason documentation is usually either missing or is not updated frequently.

Security control proposal

Having documentation in the same repository as the code, makes it easier for developers to update the documentation files. Moreover, using VCS (version control system) makes tracking changes easier. When content is automatically built and rendered using CI/CD pipelines, it makes publishing and updating documentation easier. Anyone can review, update or propose changes to the repository. And having it written in text based format, such as markdown, makes it easy to browse even in the code editors.

Reference implementation

Hugo

Hugo is a static site generator. It is used to generate static website from markdown files. You can use themes to customize your documentation. Hence, users would always find a familiar interface, when browsing documentation to your products.

To get started with Hugo see its Quick start guide.

In case your project is hosted on Gitlab, you can use the Gitlab Pages. The pipeline job that deploys contents of your documentation website would look something like this:

image: registry.gitlab.com/pages/hugo:0.73.0

variables:
  GIT_SUBMODULE_STRATEGY: recursive

test:
  script:
  - hugo
  except:
  - master

pages:
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - master

Practical implementation

Hugo

The source code of this website can serve as an example implementation of documentation site being served using Hugo and Gitlab Pages. Website domain is configurable and Gitlab will even handle TLS certificates for you.

Also many products within Pan-net use Hugo for documentation rendering. Usually one of the jobs in .gitlab-ci.yml is dedicated to building the documentation.