Any software project worth building requires good documentation. How do you enable your team to maintain it?
this.md to… this.pdf.
CD can also be “Continuous Documentation”
Communicating and documenting different aspects of a software project should be done by the whole team (not just a project manager or developers!). Documentation should evolve during project execution, so the project’s goals, architecture and final results get described.
Good documentation, like quality, should not be an afterthought, it should be built-in the process of software creation.
As not all projects have tech savvy clients, we cannot ask them to check out our project’s code and read thorough it to understand it. In addition, we do not always want to have our project documentation public, so creating a documentation website is not always practical.
If we want to follow Continuous Delivery principles, our documentation should be always potentially shippable as well.
Requirements for documentation
I wanted to provide our customers with up to date documentation in a format they could consume and archive (and e-mail to their bosses), so our requirements our Continuous Documentation efforts require that:
- Docs should kept up to date by any team member (not only developers) easily.
- They should be versioned along with our code, so we can maintain a single source of truth about the project.
- Documents should be formatted as in Word or PDF, so that managers and other members of the customer’s team could consume and share it easily.
- Updates to the documentation should require minimum manual work from our part to maintain our documents.
- We should always be ready to provide our document to anyone who asks for it.
Solution using Pandoc
I designed a solution, which can eventually be automated in a delivery pipeline. Our team:
- Created markdown files (
.md) which held the documentation introduction for each part of the project. (If you haven’t used markdown, I strongly recommend you try it to write documents. In fact, the page you are reading now has been written in markdown. )
- Created a template for documentation, it can contain the header and footer of the company or customer, as well as text and heading styles. Microsoft Word provides a template functionality by creating
.dotfiles, more information here.
- Renamed and re-organized our existing markdown files, so they follow a specific order (more on that later).
- Automated the process in our CI tool, so, potentially a new artifact (our .docx file) can be created with every commit or release.
- When delivering to customer, we would still tweak the file to make it presentable, for example, fixing spacing issues or centering images.
I used Pandoc, an extremely versatile open-source command to create a manage documents in different formats from a CLI. It is compatible with Linux and Windows, so it was possible for different members of the team to see the final document as they updated documentation.
To automate the process, we added it to our CI pipeline, so we installed Pandoc in our runner. For example, in your
gitlab-ci.yml you can have:
... doc: script: - pandoc --reference-doc=template/template.dotx -o generated/ documentation_$(date +%F_%H-%M-%S).docx -f markdown -t docx *.md ...
This command tells Pandoc which files are to be added to the documents, and in which format to input and output them. I also have a file name scheme to store new versions of the generated file (we use dates to easily keep track of the files changes).
Note: The naming of the files becomes important. To keep the final Word document sections in a specific order, we name our files
002_next_section.md and so on…
Outcome: A beautiful document
I cannot publish the documentation of our customer’s project as it is private, but I can show the outcome on one of my own published articles. This is the generated result:
These two pages show how images are supported:
- Keep the paths to our images relative inside your git project.
- Code samples such as (```) do not automatically style as monospace.
- Images are not center by default, so this is a manual step.
Disclaimer: The MCON logo is trademarks or registered trademarks of MCON.