Every developer is responsible for delivering documentation at some point during or after the development process. Sometimes, writing these documents is a hard, difficult and boring task, especially for developers, but everyone has personal notes about the project spread across different files or applications. Why not generate a deliverable document from all of this?
There are several tools to create documentation during the development process, but these tools have some drawbacks that make this process very tedious; just to mention a few:
- The tools are not included into our IDEs, code repositories, development environments, etc.
- These tools are usually not compatible with each other, i.e.: some tools require writing comments in XML format or another language to generate documentation, often leading to duplicating notes we had already written.
- There is a learning curve to get used to these tools which consumes valuable time for the developer.
- When working with other developers or team members, creating collaborative documents can be a challenge, since it requires dealing with permissions, sharing files, synchronizing documents, or juggling different versions, just to mention a few problems.
- If we want to document how we’ve built a CI/CD pipeline for a particular customer, and make a blog post about it, we need to create two different documents and do some rework on each one.
- Some companies or clients want to apply their own styles to documents, which include headers, fonts, colors, company logo, footer, etc. This adds more work to the developers when writing the documents.
All these problems cause a lack of enthusiasm when it comes to documenting as well as the annoyance that this type of task represents for some developers.
Confronted with these problems and seeing the need to automate or simplify in some way the documentation process, we were thinking about a process that can generate deliverable documentation from personal notes following some minimal guidelines that every developer already knows.
These personal notes are simple text files that are the result of team meetings, requirement gatherings, talks with the customer, estimation processes, architecture, development, testing, deployment, etc.
As a way to mitigate these downsides, we created a tool to make the process of generating documentation easier. This tool will be explained in detail in another article.
To create our tool, we decided to use the MD markup language, a specification that every developer knows. This markup specification allows us to use a common base to apply a style template and format the document according to the output that we want to produce.
There are several free tools to show in real-time what our MD document looks like as we write it, such as CodiMD.
To learn more about the specification of MD this is an excellent starting point: https://spec-md.com
As we mentioned, in a coming article we will deal in detail both with the technical approach we used to create our tool as well as the good practices to take into consideration when you are writing a document using MD.
