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:
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.
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.