The term software documentation covers all the docs you create to describe how the software works, from the project ideation to its release.
Since developing software products is a complex process, it’s not possible to cram all the information into a single document—that would confuse developers and users alike.
Instead, there are different types of software documentation, each of which addresses a specific area of the product.
So, let’s dive into this constantly evolving world and see how you can enrich your product with different types of docs.
Process Documentation
Process documentation is a broader category of software documentation that describes activities regarding product development.
The most common types of process documents are product plans, estimates, roadmaps, and schedules. All these concern the future of the product.
To illustrate the purpose of process documentation in general, the following image shows GitHub’s publicly available roadmap.
As you can see, the roadmap outlines the planned activities for GitHub’s software development.
A plan structured like this lets viewers and developers examine the areas of planned work, specific projects, and the estimated schedule for completion, which are common elements of most types of process documentation.
GitHub goes a step further and lets viewers browse details of each ticket from the roadmap. For instance, this is the timeline you see when you expand the API versioning ticket.
That way, users can see specific development actions that were taken previously and get insight into future developments. And that brings us to the primary purpose of process documentation.
By sharing your process documentation externally, you can manage stakeholder expectations.
An overview of your plans will prevent potential discrepancies between what users, investors, or clients expect of the product and what you’re actually planning to deliver.
In addition to the publicly shared process documentation, software companies frequently create internal docs with more precise deadlines and exact tasks.
However, note that process documentation can also include the records of activities from the previous development phases.
Release notes and reports are the types of documentation commonly used to communicate the product’s progress.
Reports and notes vary in scope. Some, usually the publicly available ones, only contain the updates about what has changed in the software.
On the other hand, reports designed for clients and investors provide more details about the team’s performance and resource analysis.
If your project is not that convoluted, you may not need documentation that explains your previous actions.
However, you can’t go wrong with creating process documentation reflecting your future plans because these docs serve as a guide for both your developers and users, clarifying the product’s path forward.
Requirements Documentation
This documentation type clarifies the software’s purpose and scope, together with the technical requirements you need to achieve the goals you’ve set.
In a new city, you probably can’t find a desired location without using Google Maps for navigation. Similarly, it’s challenging to build software without orientation.
This is why creating requirements documentation is the first step you take before starting software development.
In a way, this type of documentation navigates your future development activities.
A prominent subcategory of requirements documentation used in software development is a software requirements specification (SRS).
So, let’s analyze an SRS to see what makes it such an invaluable document.
We’ll use the document created by Joel Spolsky, the founder of Fog Creek, the company you may now know as Glitch.
The document starts with an overview of the project.
As you can see from the table of contents, it covers all crucial SRS elements, such as the product goals, features, software architecture, and user experience.
All these elements help inform the client of what they can expect from the product and how the development team will carry out the project.
Simultaneously, the SRS helps developers and project managers divide the project into manageable, actionable chunks.
Since consistency plays a significant role in software documentation and development, Spolsky’s SRS also includes a section about coding conventions.
The conventions only take a page, but they ensure the uniformity of the code across the entire project.
Of course, functional requirements make up a large portion of requirements documentation.
Determining the inputs and the outputs of the software in advance provides your team with guidance on how to construct the product.
All in all, requirements documentation is the essential part of each software development project that serves as the product’s blueprint.
If you want a structured approach to developing your software, make sure you dedicate enough time to this type of documentation.
Software Architecture Documentation
While requirements docs cover the software product as a whole, software architecture documents focus on the design and architecture of the product.
Here at Archbee, we use this type of documentation to see how the software is structured without digging into the code.
In this section, we’ll examine the software architecture document created for TED, the eTendering solution of the European Union.
By default, software architecture documents begin with a table of contents that navigates developers through the document.
And since the point of these docs is to represent the architecture at a glance, you’ll notice that they’re usually full of visual elements, especially diagrams.
Here’s one depicting the TED system modules.
The diagram is followed by a brief explanation of each module.
The explanations are purposefully concise, and developers interested in more details can find them in separate sections.
It’s worth noting that these documents usually don’t list each architectural decision. Instead, they offer a look at the guiding architecture principles that developers use to engineer the product.
For instance, the following figure shows how Spring MVC components should interact with the application and data access, but it’s up to developers to create the solution.
An additional advantage of writing software architecture documentation is that you can use the docs to communicate with other developers or clients about the software even before you build the first version.
Once you create the diagrammatic representation of the solution, you’ll be able to describe user stories without first having to design and implement all the UI elements.
So, if you want to have an informative overview of the entire product, you should consider asking your lead architect to create software architecture documentation.
Source Code Documentation
Source code documentation is written by developers, for developers. This type of software documentation explains how certain potentially confusing parts of code work.
The common forms of source code documentation are README docs and comments embedded in the code itself.
Keep in mind that you don’t need extensive documents for each line of code. On the contrary, you’ll preserve the clarity of the code by only documenting its most confusing aspects.
Here’s an example of effective code documentation created for a deep-learning algorithm. The README file first introduces the project, describes its structure and lists requirements.
Then, a look into the code repository reveals how the project is coded.
The screenshot below shows comments from lines 15 to 20 that clarify the function from line 14.
Comments in the documentation explain what each function does, describe input parameters and return values, mention potential edge cases, and more.
Still, if you open the repository, you’ll notice that most of the code is clear enough not to need comments.
Now, let’s examine a possibly perplexing piece of code.
To establish context, we should mention that this project aims to detect what type of activity a user is performing based on their phone and watch sensor data.
However, in line 175, the author has added code to remove parts of the sensor data.
The removal might confuse the readers, so the code is prefaced with the comment that explains that the data was dropped because those values are constant regardless of sensor input.
While documenting code does take some effort, it will save you much more time down the road once you get to code maintenance or introduce new developers to your team.
So, if you want to make future software production easier, you should encourage your devs to document as they code.
Quality Assurance Documentation
If you’re aiming to provide the best user experience, quality assurance is an obligatory step in software development.
You can streamline the QA process by creating the supporting documentation consisting of test strategy, test cases, and defect reports.
QA specialists rarely dive into testing without a strategy in place. The strategy is usually outlined in documents describing what should be prioritized in testing and the planned testing procedure.
However, specific testing details are presented in test plans.
These documents specify the features to be tested, criteria, strategy description, and deadlines.
A solid test plan will help your team carry out quality assurance quickly and decisively.
Moreover, it will allow you to avoid duplicate or unnecessary testing, keeping costs and resources under control.
Next, quality assurance documentation also covers test cases. They define the exact actions that testers need to perform to validate a specific aspect of the product.
The screenshot above shows how KeenEthics, a software development company, structures its test cases.
Their test cases cover elements common for this sort of documentation, such as expected and actual results, test status, and additional comments.
To make the QA documentation complete, software testers also compile defect reports. These reports record unwanted issues with the product.
Defect reports are an essential part of the QA documentation because they communicate the software issues to developers and other stakeholders, ensuring transparency in the development process.
All in all, since testing is an obligatory part of software development, you should create QA documentation to maximize the efficiency of the process.
API Documentation
We’re living in a multi-platform world, where the ability to integrate plays a crucial role in the success of software products.
If you’ve designed your product so that it integrates with others, you need to complement the product with clear API documentation.
A standard practice in API documentation is to preface the docs with an introduction that tells the users about the business benefits they get by using your product.
Here’s an example of a well-written intro to API reference created by CallerDesk, a cloud telephony solution.
What makes this introduction so good is its simplicity. There are no distracting calls to action—only a concise overview of what you can do with the API.
The aim of this type of software documentation is to equip developers with all they need to know to work with the API, so most API documents contain details about return types, classes, functions, and arguments.
Well-written documentation guides developers through APIs, so it’s a good idea to supplement the documentation with a description of each API, like the one you can see in the following example.
By making your API documentation approachable, you’re increasing the usability of your product. And when your product is easy to use, your user adoption is likely to increase.
Considering that the API management market grew by 24% in 2020 and is expected to grow, now is the right time to polish your API documentation if you haven’t already.
And if you don’t think your developers have enough time to deal with documentation, you could consider hiring an API writer to enhance the quality of your docs.
User Documentation
Unlike the ones we’ve seen so far, our final software documentation type is written exclusively for end-users.
User documentation shows regular end-users how to navigate the product and provides them with helpful resources along the way.
Although most companies strive to make their software products intuitive, you still have to plan for those cases when users have uncertainties about using particular features.
This is where user instructions, tutorials, manuals, and FAQs come in handy.
It’s also a common practice to combine all these subcategories of user documentation into a single knowledge base.
For instance, Vizury, a customer engagement platform, has a unified documentation center that describes the product, walks the users through its features, and answers frequently answered questions.
In addition to a neatly categorized FAQ section, Vizury users can also find the glossary that explains all the terms they might encounter when using the product.
Documentation organized like that allows users to troubleshoot the issues without getting the support involved, increasing their satisfaction with the product and reducing your customer support costs.
Of course, user documentation is created with entry-level users in mind, so you’ll notice that most user-focused docs incorporate straightforward instructions and plenty of explanatory screenshots.
So, if you want the users to get the most out of your product, you have to tell them how, and you can do exactly that by creating navigable and precise user documentation.
Conclusion
A software product is only as good as its documentation, and as you can see, software documentation is quite a wide area.
Still, exploring the software documentation types will help you determine the ones you need to create for your product.
Once you plunge into the development process, you’ll be glad you have requirements and architecture documentation to guide you along the way!
