If you are a developer or work with software development, you may have wondered about the importance of documentation in your daily life.
Software documentation is a set of written information, accompanied by videos and images that serve as a guide, i.e., a tutorial, for the use of a service or program. It helps to clarify doubts, explain the functionality and operation of the system, and ensure that all users of your technology have access to the necessary information.
With a focus on this type of documentation, we have prepared this material to explain the role of documentation in secure development and to present Conviso Docs, the documentation of Conviso Platform.
The role of software documentation
Technical documentation represents an essential source of guidance for developers, regardless of skill level. It is very common to hear that poor documentation can be the biggest obstacle to using a product or carrying out a process during application development.
To understand what makes documentation good, we first need to understand the purpose of documentation. What is its purpose? Why is having effective documentation so important?
It’s simple, good documentation addresses the questions of developers and other professionals involved.
In a case study research on the subject, it was observed that programmers usually ask the same questions before starting to develop. In this research, they categorized all these questions into 5 categories:
- How (example code): How to use API X? How to implement feature Y?
- What (specific code reading): What does this script do? What is the name of the enumeration?
- Where (code location): Where is the code to do X? Where do we configure the environment variables for Y?
- Why (determine impact): Why isn’t my change working?
- Who and when (metadata): Who edited this code and when? Who can help review this code?
In summary, good documentation should:
- Be easy to find.
- Be easy to read/write and update.
- Be current and clear.
- Offer complete context.
Furthermore, documentation is essential to assist in the secure development process, guiding programmers on best practices and preventing common errors.
But why is documentation so important even when it comes to AppSec?
Well, it’s simple: it can have a huge impact on the business and, consequently, on its users. Imagine if a single topic in the documentation could alert developers to a possible security risk that they hadn’t considered before in their code. This would prevent several problems!
In this way, it can be a primary source of learning about secure development for your language. Suppose a developer has not thought about protecting their software against SQL Injection. The documentation can address this risk and teach them to consider it in future projects. For more information, see this article.
Furthermore, it is important to keep in mind the documentation of the security products you use. This documentation is essential to ensure that you are aware of the capabilities and features of this product, as well as its correct and efficient use. By having knowledge of this documentation, you can maximize the support offered by this tool in your secure development process.
Introducing Conviso Docs – Conviso Platform’s documentation
Conviso Docs is the official documentation of Conviso Platform and is an essential tool for our developer users to use our products efficiently and autonomously. It can be accessed through this link.
In Conviso Docs, you will find general information about the platform and guidance for each of the features, including common issues related to product use.
Additionally, there is more technical information for developers, SREs, and security professionals, with detailed descriptions of the different components of the product, such as the API, integrations, and CLI.
The documentation is open source, and everyone is invited to contribute!
How to update our software documentation
We believe that collaboration is the key to evolving and making our documentation more complete and accurate. Here are the steps you need to follow to contribute:
- Fork the repository and create a branch following the pattern “feature/branch_name”.
- Make your changes on the branch of your fork, making sure it is always up to date with the main branch.
- Open a Pull Request (PR) on GitHub, detailing all the changes you made and the reasons behind them.
Now just wait for our team to review your PR and, if approved, your contributions will be incorporated into our documentation. To check the full contribution process, just access CONTRIBUTING.md.
In addition to the process mentioned above, we encourage our users to raise questions, corrections, criticisms, and suggestions about our documentation by creating “issues” in our repository on GitHub.
Don’t neglect software documentation!
In this article, you can understand the importance of maintaining and writing clear documentation, how it works, and how it can facilitate and support the daily life of developers. We aim to highlight the importance of this resource for learning about secure development, particularly in understanding the risks of using a technology improperly.
For this, collaboration is essential to keep the documentation up to date and complete. By contributing to the documentation, users can help evolve and make the documentation more accurate and complete.
Authors:
Gabriel Galdino – Developer Advocate
Giovanni Martins – Software Engineer
