<\/p>\n\n\n\n
Documenting is instructing or informing someone about the news and evidence related to a specific topic. Therefore, when we write technical documentation, It\u2019s important to understand that we are writing for humans, not machines. We try to help the reader understand the complexity of our system, and to achieve this, we can make use of our extensive and rich language<\/strong>. However, the tools we have for creating documentation don’t always make things easy for us.<\/p>\n\n\n\n For example, in the case of OpenAPI<\/a>, the most widely used tool for API documentation, we can only add arbitrary text in certain \u201cdescription\u201d fields. This falls short if we need to elaborate on the explanation of a resource, display examples, images, etc.<\/p>\n\n\n\n Furthermore, JSON and YAML formats are highly oriented towards machine-generated or machine-interpreted purposes, making it very challenging for humans to create and maintain them. Even though there are tools to simplify editing, it’s a format where syntactical definition takes precedence over semantics.<\/p>\n\n\n\n At Devengo, we believe that documentation should be oriented towards people<\/strong>. That’s why we’ve always advocated for using Markdown whenever possible. On the other hand, we also understand the value of syntactical definition when generating schemas, validators, clients, etc. Wouldn’t it be great if we could combine both worlds? As a matter of fact, that tool has existed for years, and it’s called API Blueprint<\/a>.<\/p>\n\n\n\n API Blueprint is a tool that was born in 2013, allowing us to use Markdown as a language to document our APIs. Many people reading this article may have tried it at some point and considered it outdated because it lost the battle against OpenAPI. The latter tool became the industry standard, and all the focus has been on it. However, we believe it is still entirely valid because it provides the principles we mentioned earlier.<\/p>\n\n\n\n The number of artifacts we use in Blueprint is minimal and easy to learn.<\/p>\n\n\n\n It’s the definition of the different data types that the API handles.<\/p>\n\n\n\nMarkdown FTW<\/strong><\/h2>\n\n\n\n
Data Structures<\/strong><\/h3>\n\n\n\n