How do I create software documentation?

New job, new project - and immediately in the middle of the code. The first requirements arrive, the system is already running productively and your task is to quickly familiarize yourself with the system. But instead of clear instructions, you find scattered information, outdated comments in the code and colleagues who no longer know exactly how module XY actually works. The official documentation? Not available - or buried somewhere deep in a long-forgotten wiki.

What should actually be a structured introduction to software development turns into detective work. You search, ask, interpret - and lose time. Because without comprehensible, up-to-date and accessible documentation, every task, no matter how simple, becomes a challenge. Yet it could be so much easier.

This experience exaggerates the approach often taken in companies when new employees arrive and don't know how to start their work. We say that doesn't have to be the case! In software development, this problem is usually solved by software developers and other team members writing down important results of their work for future project members.

This allows newcomers to hit the ground running when they arrive at a new company or project team. Talk about thorough software documentation. Our exaggerated case study shows why software documentation plays such an important role in the daily work of a developer. Today we'll show you what software documentation is all about!

Why is software documentation necessary?

Technical documentation plays a crucial role in every software project. It makes the code easier to understand, facilitates the training of new team members and reduces maintenance costs in the long term. Without structured documentation, it can be difficult to rectify errors or implement new functions later on.

At FIDA, we rely on writing complete technical documentation for various reasons:

• Traceability: other developers (or yourself) need to be able to understand months or years later how the software works.

• Efficiency: Well-documented software reduces communication effort and speeds up development processes.

• Maintainability: Errors can be rectified more quickly and changes can be made in a targeted manner.

• Onboarding of new developers: New team members can familiarize themselves more quickly thanks to structured documentation.

• Scalability: Clear documentation makes it easier to further develop the software and add new features.

As you can see, investing in good software documentation saves time, money and frustration in the long term - for both developers and users.

Software projects are developed in teamwork

Critics might argue that it is not the job of a developer to write handover protocols, as it wastes unnecessary time that is not available in the tightly scheduled, usually agile project environment anyway.

However, this supposedly lost time is made up for by the time gained through faster and less complicated onboarding. A new software developer can familiarize themselves with documents more quickly than having to make their own notes on every topic every time.

Even complete documentation of the work processes does not rule out the possibility that some questions will remain unanswered at the end, but by setting up a knowledge database right from the start, someone who is not yet familiar with the project can quickly and efficiently gain an overview.

Admittedly, writing is not a primary skill of a programmer. However, the ability to put technical knowledge and know-how into understandable words and create a user manual for users is a bonus that can distinguish a good application from an outstanding one.

Non-technical skills are also required to work efficiently and cooperatively in a team. Almost every software project is developed in a team, which is why a software developer today must also be able to work in a team - especially if it is a large and innovative project! Especially in large teams or long-term projects, clear software documentation is crucial for the maintainability and scalability of the code.

Good to know: Some companies employ technical writers to ensure the consistency and quality of all documentation. Technical writers allow developers to focus more on what they do best - writing code. However, they often need insights (and code comments) from your team to create understandable documentation.

Handover to developers

As developers do not simply start programming independently of other team members, there is almost always a project handover to the developers at the start of a project. The handover begins with the project briefing: this contains the concept according to which the project is to be designed and contains important information about what the application should look like, what functionalities it should have and what technical requirements it must fulfill.

The project briefing is often referred to as "requirements". It does not normally list any specific activities or tasks, but provides a kind of table of contents of the required functions of a software program that all stakeholders involved can use as a guide.

All this information is transferred to a project management tool before the actual development work begins. Tickets are created for each part of the project, tasks are estimated using story points, and the workflow is defined using a visual board, Kanban or an alternative form. This way you can easily see who in your team is working on what, what needs to be done next and approximately how long each task will take.

What belongs in software documentation? Steps for a successful handover process.

But what happens at the other end of the process - when your part of the project is complete? As a developer, you need to prepare your work so that it can be passed on to the next step, e.g. to user acceptance testers. You also need to make sure that your code base is manageable and navigable for future developers who work with it and, for example, add new functions or make corrections.

In the best case scenario, you should take the following steps when you pass your application on to the next person in line in order to prepare it optimally:

1. Commenting your code

2. Documenting the classes, components and methods in your code

3. Creating a manual for setting up the project ("Getting started", "Quickstart Guide", ...)

Sounds like a lot of work? It may be, but it's an important step, not only for your team colleagues, but also for you as the original developer, to ensure traceability and verifiability at all times during the course of development.

How to create effective documentation

1. comments in your code

Let's start with the first step - commenting your code. Many developers ask themselves: Are comments in code really necessary? The answer is - it depends!

Basically, well-structured code should speak for itself. This means that variables, functions and classes should have meaningful names that clearly reflect their function. In this way, the code remains readable and understandable without the need for superfluous comments.

However, there are situations in which comments are indispensable:

• When a complex or unconventional solution has been chosen that is difficult to understand without an explanation.

• To document the reasons for deciding on a particular implementation.

• To add important details that are not directly apparent from the code.

A concise comment can therefore help other developers to understand the code more quickly and develop it efficiently.

Conclusion: Write comments purposefully and deliberately - not as a substitute for clean code, but as a useful addition when it is really necessary.

2. documentation of your classes, components and methods

The technical documentation of classes, components and methods plays a central role, as it helps developers to quickly find their way around the code and make informed decisions. Detailed documentation ensures that functions and dependencies are clearly visible. This allows new developers to join a project more quickly and existing team members to work together more efficiently.

• Classes should contain a short description that explains their function and area of application.

• Components (especially in front-end frameworks such as React or Angular) benefit from documentation of props, states and (lifecycle) methods.

• Methods and functions should explain parameters, return values and special implementation details.

Especially if you are dealing with object-oriented languages such as TypeScript, JavaScript (with classes), Java or C#, it is common to sketch UML diagrams, which can be useful for the entire software documentation and should therefore definitely be included in the documentation. This is because these structure diagrams describe classes, attributes, methods and inheritance visually, which provides clearer access than pure code. This makes it easier for beginners to understand the structure and relationships between components or modules. Useful tools for this are PlantUML, Mermaid or Draw.io.

3. create a manual for use

Once you have written your code and commented it neatly, you can now move on to describing the overall structure of your development. You should also have the user of the software in mind. This step is usually carried out after programming and serves to prepare users for using the new software. The most important user information includes the installation instructions, which describe the installation process with the help of step-by-step instructions and screenshots. In addition, chapters on best practices can be added to the software documentation, as well as tips for further use of the code or its implementation in other applications.

However, your team ultimately decides what ends up in the documentation. Because only the project team knows what is important for the work on the project, be it in the support teams or with the users, as it determines the target group that will use the product from the outset.

There are already many open source solutions on the market for creating a user manual, which you can use to describe how others can start working on the project or use your software product. Helpful tools for developers who write software documentation are Docusaurus, readme.io or MkDocs. Below we present some useful software documentation tools that help developers to document their projects efficiently.

The most popular software documentation tools for developers

1 PlantUML - Create diagrams easily

PlantUML is a popular open source tool for creating UML diagrams using a text-based syntax. It is ideal for developers who want to integrate diagrams directly into their code.

2 Mermaid - Markdown-compatible diagrams

Mermaid makes it possible to create diagrams with a markdown-like syntax. It is often used in Confluence, GitHub and other tools to visualize processes and structures.

3 Docusaurus - Documentation with React

Docusaurus is a tool developed by Facebook that is particularly suitable for developers who want to write documentation with Markdown and use a React-based interface.

4. draw.io (diagrams.net) - drag-and-drop diagrams

Draw.io (also known as diagrams.net) is a visual tool for creating diagrams and flowcharts. It offers an intuitive user interface and integrates with cloud services such as Google Drive or GitHub.

5. mkDocs - Fast static documentation pages

MkDocs is a simple but powerful tool for creating static web pages for technical documentation. It supports Markdown and is easily configurable.

6 Swagger - Automate API documentation

Swagger (OpenAPI) is a standard for the documentation of REST APIs. It enables developers to generate and test interactive API documentation.

Choosing the right documentation tool depends on the requirements of your project. While PlantUML and Mermaid are ideal for diagrams, Docusaurus and MkDocs offer powerful solutions for text-based documentation. If you want to create API documentation, you should consider Swagger.

How do you document software correctly?

Good software documentation should be clear, structured and comprehensible. To ensure this, it is important to observe relevant standards that set the standard for technical documentation. Effective documentation explains how the software works and clearly presents the relationship between the various components.

When creating technical documentation, it is helpful to use different formats: In addition to pure text, code examples and screenshots should also be integrated to visually illustrate complex processes. Especially in production, documentation should be updated regularly to correctly reflect changes in the code and new features.

The combination of a clear structure, visual elements and standardized specifications makes documentation understandable and useful not only for developers, but also for other stakeholders.

Other helpful tips for good software documentation

1. Use a uniform structure: Use a clear hierarchy with chapters and sub-chapters so that readers can quickly find relevant information.

2. Write comprehensibly and precisely: Avoid unnecessary technical terms or overly long explanations - the documentation should be easy to read.

3. Add practical examples: Code snippets and use cases help readers to put theory into practice.

4. Keep the documentation up to date: outdated documentation leads to misunderstandings and errors. Schedule regular updates.

5. Use version control: If possible, save your documentation in a version control system (e.g. Git) to be able to track changes.

6. Integrate the documentation directly into the development process: Automatic generation of API documentation or README files helps to integrate documentation seamlessly.

7. Collect feedback: Let team members or users test the documentation and improve it based on their feedback.

With these tips, you can ensure that your documentation is not only complete, but also useful and easy to understand for everyone involved.

What types of development documentation are there?

Documentation informs other developers what each element of the project does and gives them enough information to use it in the project. For example, it's safe to say that some programmers would find it difficult to realize their own projects without comprehensive documentation and the examples that are available in most GitHub repositories. Although creating documentation takes time and dedication, it is an important part of a developer's job and essential when delivering projects.

On the other hand, documentation can also be seen as a kind of user manual - a document designed to help those developing the software to understand specific functions and perform specific tasks. The user manual for the React UI library, for example, explains how users can embed the library in their own software. Similarly, a user guide for a specific proprietary or open source API could outline the steps for retrieving or updating data. The documentation should fulfill the following three functions:

• Explain the functionalities of the product

• contain essential project-related data

• serve as a basis for discussing the technical aspects of a project

What kind of documentation should I write?

When you are looking for a tool to create software documentation, there is no right or wrong. Rather, your team needs to decide what belongs in the document and what tools they want to use. First of all, you need to discuss what type of documentation you want in the first place, or whether you should choose a hybrid of several types.

The types of software documentation

There is no one tool that provides you with all the documentation that enables another software developer or user to use a piece of software or implement it in other applications. Rather, several tools can help developers create meaningful and coherent explanations of their software.

Many of the latest tools also offer AI-based add-ons, and depending on a team's documentation needs, utilizing them can lead to faster and better results.

There are also some other differentiators in technical documentation. Depending on your specific role on the development team, some types of documentation are more important than others.

As a backend developer, you probably don't need to know how to create a button or form element; a frontend developer doesn't need documentation about the database schema either. Let's take a look at some of the different types of documentation.

API documentation

API documentation is one of the most common and necessary types of documentation for developers, mainly due to the need for API endpoints. Not only do you need documentation for existing APIs to use them in your own projects, but also for your own APIs when you pass them on to frontend developers, for example.

Without knowing what endpoints are available, what kind of data can be retrieved and what information needs to be sent, an API would be pretty useless! Frontend developers in particular need to know how the data they will be working with is structured so that they can format it correctly on the frontend.

API documentation is usually created by the backend developers of a team. This documentation is crucial for the developers working on the frontend. It can be in the form of a text document or an HTML document created with JSDoc or Swagger.

Application documentation

The application documentation contains detailed information about a code base, e.g. which classes exist, what their purpose is, which methods they have, which parameters the methods accept and which data they return. This is where all the more detailed information about your code is located.

This type of application documentation is usually stored in a place that can be accessed by everyone involved in the development process, e.g. in the GitHub repository for the project or on a separate website for the project. In a company, it may even be stored on internal file servers such as Google Drive or Confluence.

It should not be confused with pure user documentation, which focuses primarily on the end user. It serves the user as a manual for using the software, through which the user learns how to use the software. At the same time, it is also intended to explain how important steps within the application work, for example how to log in, enter data or save documents.

Documentation of a library

Software documentation is essential if you want to create your own component library for a project. After all, you need a way to quickly inform other developers about how to use the library, what methods exist, what they do, what parameters they require and what data they return.

It tells you how to install the library, provides you with sample code, contains a list of all the properties the components need (and what they do), and much more - in other words, everything you need if you want to use the library yourself.

However, users will still look at your code if they need to add a new method to the library, for example. For this reason, it is important that you write explanatory comments in your code in addition to the outward-facing documentation.

What belongs in software documentation

Other types of documentation that developers sometimes share range from database architecture information, deployment and testing guidelines, to best practices for using HTML and UI components in a project. You may also come across less technical documents such as project descriptions, user stories, user flows, personas, screen designs and assets. Even meeting notes can be included in the documentation if they are deemed important!

If you're still unsure about how to write good technical documentation, it can help to take a closer look at some well-known documentation from leading software vendors, as there's a lot to learn from them and they can give you online help on how to build your own future documentation.

When we search the internet for the most popular libraries and take a look at their documentation, we realize that there are a few characteristics that make a good technical documentation: it is clear and easy to understand for developers. In addition, the usual components of a user manual include an overview of the basics, instructions for commissioning, usable components and APIs. It is also not uncommon to find contributions and articles by experts and IT administrators within software documentation.

Conclusion

Despite these series of standards and software documentation tools, there is no one-size-fits-all solution as to how software documentation should be designed and it is ultimately always up to you and your project team to decide how extensive your software documentation should be, what you want to focus on in terms of content and how much time you want to spend on high-quality documentation of your results. Some teams prefer to document everything, while others only record the most necessary parts of a project (e.g. APIs). You should clarify this question at the beginning of your work in a project to ensure that you act (and document) according to expectations.

Are you looking for software developers who, in addition to programming, also understand how to write software documentation and can offer you added value in terms of the maintainability of the code base? Our team of experienced developers is at your side. Get in touch with us today and we'll see how we can help you!