Documentation since code.

In general, and almost always, if not always, there is no documentation. And not only theory, but above all practice, shows that without documentation a project does not scale.

Documenting is planting a long-term investment. It is a process that requires experience to be understood as necessary for the scalability of a project. Since the fruit is not immediate, it is often difficult to justify its importance.

However, this importance is sustained by several functions that documentation fulfills:

1. Bring the developer closer to development In an industry where there is so much movement of human resources, we only have the pictographic record of what a human did in it. A new developer does not necessarily have an oral record. What remains to tackle a project is the documentation.

2. Define an agreement The documentation supports a discussion and consensus of what objective to achieve. If it is in writing, it infers an agreement between provider and customer. From this, it is possible to define and justify the work involved. It also defines a single source for query and control, at best versioned.

3. Scale in quality All documentation supports the hours of analysis that a project implies. That there is nonsense in the code goes much more unnoticed than a documented inconsistency.

Finally, the difficulty involved in maintaining project documentation is an aspect that must be taken into account. In general, none of them is linear in their development: changes in technology, functionalities or UX/UI analysis add up to nonsense that establishes the irregularity of any project.

Our solution

Like good programmers who bundle different functions into as little code as possible, our team were working on an automatic documentation generator from snippets directly in the code. Yes, it is the responsibility of the developer to communicate the programming, justify his constructive decision and manifest his development. Our development integrates the documentation to the code so that it is part of the development flow.

Step by?Step:

1. When creating a new route, the developer includes the documentation within the same code
2. ?When reviewing an MR/PR, the route code and documentation are reviewed, making it easier to control updates
3. When merging a task, the updated documentation is included in the same code
4. By being part of the code, you can automate the generation and publication of documentation (Documentation CI)

Architecture

- A package that is included in our code and generates the document - A document storage - CI to automatically publish new documents to storageDocument - Web Viewer

https://www.npmjs.com/package/@grava.io/api-doc https://github.com/gravadigital/api-doc

Conclusion.

Our proposal is to bring the action of documenting (and the benefits it carries) closer to the developer. It’s not finished by any means. Still, it solves the most critical part of the demand. No tool covers 100% of the needs. We leave this open source to add the functionality that your business or paradigm needs.