How to create technical documentation for your software

Software documentation is a necessity to achieve success in the

projects, but at the same time it is perceived by many developers and companies
as a leak of productive time? How important is it?
documenting the software? Where is the boundary between the
necessary documentation and non-essential documentation?
Table of contents
1 History of software and documentation
What is software documentation?
2.1 Why is software documentation important?
3 Characteristicstcase of the software documentation
4 Types of software documentation
4.1 Documentation of the development process
4.2 Product Documentation
5 Tools for Software Documentation
5.1 Confluence
5.1.1 How does Confluence work?
5.2 Document360
5.2.1 How does Document360 work?
5.3 Doxygen
5.3.1 How does Doxygen work?
6 Conclusions about software documentation
History of software and documentation
Throughout the still short history of software, many things have been experienced.
stages in which documentation has been seen as something essential
until something undesirable. The key lies in the development processes and how the
Documentation has been weighing at each stage.
The ancient cascade process first included a process of
requested in which all the documentation of the application was carried out to
perform, along with the design of the project software. When I was
totally defined what needed to be developed. Then it began the
part of the programming. In this underdeveloped development process,
entire bibles of documentation were created with text that in the end no one read
completely. Furthermore, as it is impossible to know with total accuracy the
scope of the projects and all their facets, it was common for the
Documentation completed does not accurately reflect the development carried out.
finally.
Many years passed, across several stages that we will skip, until
that they arrived theagile methodologiesEspecially at first,
the documentation could take a backseat, as in each iteration
some small requirements are taken and there is no need to document
that which is in the process of development. However, there are various
types of documentation for the applications, even in the processes of
agile development, where it is important to specify what are the
functionalities of the developed software, to allow those who
They are going to use this software, they can know its possibilities, something above all.
important when the software clients are other machines, such as
it happens with theweb services.

What is software documentation?

Software documentation is a report that guides developers,
users and other interested parties through the use of an application. It is a
resource that provides information on how to install, use and/or
maintain software. Additionally, it serves as a technical reference for those who
They need to understand their underlying code and architecture.

Why is software documentation important?

The importance of clear and complete documentation lies in its
ability to reduce the learning curve, facilitate collaboration and
minimize long-term maintenance issues. Without a good
documentation, even the most powerful software can become inaccessible
it is ineffective.

Characteristics of software documentation

Documentation is part of the software, necessary for its correct use and
maintenance. However, carrying it out is not always easy, because it is necessary to
knowing what to document and how to document it. Important points include
the following:
The documentation must evolve with the software. The software
It changes with time and the documentation must also do so.
that serves as a faithful reflection of the developed application. A
Obsolete documentation can even be counterproductive.
The documentation must be well organized and easy to understand.
It also requires to be consulted quickly. That's why it is
preferable the creation of diagrams instead of texts.
The diagrams must be understood in the same way by everyone.
people. Therefore, it is important to use a language like UML, the
which indicates the meaning of each of the elements that form
part of the diagrams
In the case of using written language, it must be clear and concise, simple.
to understand even with less technical knowledge
In addition, we must provide a degree of navigation within
the documentation, being consistent, knowing who it is aimed at, etc.
Maintaining correct and updated documentation is a task that requires
time and when developing a project it is important to allocate the
sufficient resources for its implementation.

Types of software documentation

In software development, there are two main types of documentation.
1. The documentation related to the development process
2. The documentation that addresses the product
Let's look in detail at these types of documentation and establish some.
guidelines for each of them.
Documentation of the development process
During the software development process, it is important to carry out a
appropriate documentation to understand well what should be programmed and
how to program, especially when the project involves certain
development difficulty.
Some documents that are created in this stage are:
Requested: In this case, documents are created to know what is going to
to develop, indicating the functionalities of each actor that
interacts with the system. The requisition phase may include
diagrams such as use case diagrams, process diagrams
business, mockups of the interfaces.
Planning: During the project, it is important to know what resources
let's detail each task and how they will be organized, the times
that is estimated how long each stage will take. For that, the useful...
Gantt charts, which are usually generated using
some tool.
Development process reports: As the development of
The project is being carried out; it is essential to reflect this in a document.
performance of our development team and the time invested in
each of the disciplines (management, analysis and design, programming,
tests, deployment). Keeping track of metrics for the entire process allows us
will help to be aware of the investment made, to estimate in a way
more accurately the needs and forecasts going forward, so that
the time and money that a project will cost becomes more accurate.
Task backlog: It is very common for development teams
bring tools that allow knowing what tasks need to be performed
in each project and its urgency, with an agile system that helps to decide
which parts of the project will be undertaken in each iteration. For this reason
There are various tools similar to Trello that can be very
outlet.
 Code documentation: The code can also be documented
with libraries that allow converting comments into
documents that developers can easily consult.
Eachprogramming languagehave your own tools to
generate the code documentation from the comments, such as
Javadoc or PhpDocumentorPHP).
Product documentation
The product documentation is specially directed to users.
finals of this product and the staff that will be dedicated to providing it
maintenance or provide support. These documents are very useful.
at the moment new people join the project, since
it allows them to better understand its characteristics and have an idea
concise about the tasks that must be performed.

This documentation includes various information about the

functionalities of the applications, their implementations and the mode of use.
Among others, we can find the following documents:
System Description: This document can guide people.
they are going to manage an application, indicating what the objective is
this, what are its functional requirements, the non-requirements
functional and the restrictions or special needs of the
solutions that must be implemented.
Usage guidelines: For application users, specifying what
processes are available and how they should be used
applications.
System description: For more technical people, to help them.
to understand the solution architecture, the systems it involves and
their interactions. What requirements must the machines have
deployment, in aspects related to scalability, security and
other important factors that help with proper maintenance of
the systems.
Software architecture: If new developers join the
It is important to have documentation about how work is.
 developed the software and its main design lines and
architecture. Generally with UML diagrams that allow
understand the different pieces in a visual way.
API Documentation: Additionally, if the clients of the software are other
software pieces, as is the case with APIs or web services,
it is important to have complete documentation that
clearly specify the input and output of each process. In this
tools like OpenAPI or Swagger are excellent because
they allow us to generate all the documentation through annotations in
the code itself.
Tools for creating software documentation
The choice of the right tools for documentation
Software is crucial to simplify the process and ensure quality of
material. Here we present some highlighted tools:
Confluence
Confluence, developed by Atlassian, is a collaboration platform.
which includes advanced features for creation and management of
documentation. Its interface facilitates collaboration between teams and simplifies
the creation of technical documentation.
How does Confluence work?
This tool uses a structure of spaces and pages to organize
the information. You can create pages dedicated to different aspects of your
software, add images, tables and links, and collaborate in real time with
other team members. In addition, it integrates with other tools.
Atlassian, like Jira, for efficient software lifecycle management.
It is ideal for teams that value real-time collaboration. Its
flexibility and the ability to integrate with other tools make it
a powerful option for creating and maintaining documentation
of the software.

Document360
Document360 is a technical documentation platform designed
specifically to facilitate the creation and management of documentation
software. It also offers features focused on usability and the
personalization.
How does Document360 work?
This tool provides an intuitive 'drag and drop' editor.
for content creation. It allows for the creation of versions, the
customization of design and the incorporation of interactive elements.
the platform also offers analysis to understand how users
they interact with the documentation.

It is especially useful for teams looking for a solution focused on the

user experience. It facilitates the creation of attractive and easy documentation.
to follow, with advanced customization and analysis options to improve
continuously the material.
Doxygen
Doxygen is a documentation generation tool forcode
sourceIt is designed to analyze the code and generate documentation.
automatically, reducing manual workload.
How does Doxygen work?
This tool works by analyzing specific comments in the code
source, like comments in JavaDoc or C++. From these
comments, create documentation in various formats, such asHTML, LaTeX and
RTF. It can generate class diagrams and collaborates well with projects.
big.
It is an efficient option for development teams that want to generate
Documentation directly from the source code. It facilitates the update.
automation of documentation with each change in the code, which
improves consistency and reduces manual efforts.