Software documentation is a crucial part of working software. Whether it’s API documentation, release notes, or customer-facing help content, you can’t afford to skip over the docs when it comes to developing or shipping out software. Software without documentation is difficult to work with and costs more to maintain.The main goal of effective documentation is to ensure that developers and stakeholders are headed in the same direction to accomplish the objectives of the project.

The documentation types that the team produces and its scope depending on the software development approach that was chosen. Agile is the main development approach most organizations are using.

Here are the different types of documentation.

Product documentation describes the product that is being developed and provides instructions on how to perform various tasks with it. In general, product documentation includes requirements, tech specifications, business logic, and manuals. 

• System documentation represents documents that describe the system itself and its parts. It includes requirements documents, design decisions, architecture descriptions, program source code, and FAQs.
• User documentation covers manuals that are mainly prepared for end-users of the product and system administrators. User documentation includes tutorials, user guides, troubleshooting manuals, installation, and reference manuals.

Process documentation represents all documents produced during development and maintenance that describe… well, the process. The common examples of process-related documents are standards, project documentation, such as project plans, test schedules, reports, meeting notes, or even business correspondence.

The main difference between process and product documentation is that the first one records the process of development and the second one describes the product that is being developed.

Product or System documentation(For Developer)

System documentation provides an overview of the system and helps engineers and stakeholders understand the underlying technology. It usually consists of the requirements document, architecture design, source code, validation docs, verification and testing info, and a maintenance or help guide. It’s worth emphasizing that this list isn’t exhaustive. 

Product requirement document

A product requirement document or PRD provides information about system functionality. Generally, requirements are the statements of what a system should do. It contains business rules, user stories, use cases, etc. This document should be clear and shouldn’t be an extensive and solid wall of text. It should contain enough to outline the product’s purpose, its features, functionalities, maintenance, and behavior.

The best practice is to write a requirement document using a single, consistent template that all team members adhere to. The one web-page form will help you keep the document concise and save the time spent on accessing the information. An example of this is a confluence page.

User Experience Design documentation

User experience design begins at the requirements stage and proceeds through all the stages of development, including the testing and post-release stages. The process of UX design includes research, prototyping, usability testing, and the actual designing part, during which lots of documentation and deliverables are produced.

The UX documentation can be divided into stages. The research stage includes:

• User personas
• User scenario
• Scenario map
• User story map
• UX style guide

User Personas are created and documented during the research stage. The information gathered during user interviews and surveys is compiled into functional user persona documents. User personas represent the key characteristics of real users, focusing on behavior, thought patterns, and motivation.

A user scenario is a document that describes the steps a user persona will take to accomplish a specific task. User scenarios focus on what a user will do, rather than outlining the thought process. The set of scenarios can be either visual or narrative, and describe the existing scenarios or future functionality.

Scenario maps are used to compile the existing user scenarios into a single document. Scenario maps show all possible scenarios available at a given moment. The main purpose of a scenario map is to depict all the possible scenarios for every single function, as well as intersecting scenario steps.

A user story map is formed from the backlog of the product. This type of document helps to arrange the user stories into future functions or parts of the application. A user story map can be a scheme, or a table of user stories grouped in a particular order to denote the required functions for a certain sprint.

The UX style guide is a document that includes the design patterns for the future product. It also describes all possible UI elements and content types used, defining the rules of how they should be arranged and work with each other

On the stage of prototyping and designing, a UX designer often works with the deliverables and updates documentation on par with other team members, including product owner, UI designers, and development team. The most common documents produced at these stages are:

• Site maps
• Wireframes
• Mock-ups
• Prototypes
• User flow schemes or user journey
• Usability testing reports

User flow or user journey schemes help the team to map the steps a user should take through the whole product. The main task of a user flow scheme is to depict the possible steps a user may take, going from page to page. Usually, the scheme includes all the pages, sections, buttons, and functions they provide to show the logic of user movement.

Wireframes are the blueprints for future UI. Basically, wireframes are the schemes that show how to arrange the elements on the page and how they should behave. But, wireframes don’t depict what those elements should look like.

A mock-up is the next product design stage, showing the actual look and feel of a product. Basically, mock-ups are static images representing the final product design.

A prototype is a mock-up that you can interact with: click some buttons, navigate between different pages, and so on. A prototype can be created in a prototyping tool like Sketch or MockFlow . Using templates, UX designers can create interactive mock-ups on the early stages of development to be employed for usability testing.

A usability testing report is a short-form feedback document created to communicate the results of usability testing. The report should be as short as possible, with visual examples prevailing over text.

Software architecture design document

Software architecture design documents, sometimes also called technical specifications, include the main architectural decisions made by the solution architect . Unlike the product requirement document mentioned above that describes what needs to be built, the architecture design documentation is about how to build it. It has to describe in what way each product component will contribute to and meet the requirements, including solutions, strategies, and methods to achieve that. So, the software design document gives an overview of the product architecture, determines the full scope of work, and sets the milestones, thus, looping in all the team members involved and providing the overall guidance.

Source code document

A source code document is a technical section that explains how the code works. While it’s not necessary, the aspects that have the greatest potential to confuse should be covered. The main users of the source code documents are software engineers.

Source code documents may include but are not limited to the following details:

• HTML generation framework and other frameworks applied
• Type of data binding
• Design pattern with examples (e.g. model-view-controller)
• Security measures
• Other patterns and principles

Try to keep the document simple by making short sections for each element and supporting them with brief descriptions.

Product: User documentation

As the name suggests, user documentation is created for product users. However, their categories may also differ. So, you should structure user documentation according to the different user tasks and different levels of their experience

End-user documentation

The documentation created for end-users should explain in the simplest way possible how the software can help solve their problems. Such user instructions can be provided in the printed form, online, or offline on a device. Here are the main types of the user documents:

The quick start guide provides an overview of the product’s functionality and gives basic guidelines on how to use it.

The complete manual includes exhaustive information and instructions on how to install and operate the product. It lists the hardware and software requirements, detailed description of the features and full guidelines on how to get the most out of them, example inputs and outputs, possible tips and tricks, etc.;

The troubleshooting guide gives end-users information on how to find and resolve possible issues that might arise when using the product.

System administrators’ documentation

System administrators’ documents don’t need to provide information about how to operate the software. Usually, administration docs cover installation and updates that help a system administrator with product maintenance. Here are standard system administrators documents:

• Functional description – describes the functionalities of the product. Most parts of this document are produced after consultating a user or an owner.
• System admin guide – explains different types of behaviors of the system in different environments and with other systems. It also should provide instructions on how to deal with malfunction situations.

Process Documentation

Process documentation covers all activities surrounding product development. The value of keeping process documentation is to make development more organized and well-planned. This branch of documentation requires some planning and paperwork both before the project starts and during the development. Here are common types of process documentation:

Plans, estimates, and schedules. These documents are usually created before the project starts and can be altered as the product evolves.

Reports and metrics. Reports reflect how time and human resources were used during development. They can be generated on a daily, weekly, or monthly basis. Consult our article on  agile delivery metrics to learn more about process documents such as velocity chats, sprint burndown charts, and release burndown charts.

Working papers. These documents exist to record engineers’ ideas and thoughts during project implementation. Working papers usually contain some information about an engineer’s code, sketches, and ideas on how to solve technical issues. While they shouldn’t be the major source of information, keeping track of them allows for retrieving highly specific project details if needed.

Standards. The section on standards should include all coding and UX standards that the team adheres to along the project’s progression.

The majority of process documents are specific to the particular moment or phase of the process. As a result, these documents quickly become outdated and obsolete. But they still should be kept as part of development because they may become useful in implementing similar tasks or maintenance in the future. Also, process documentation helps to make the whole development more transparent and easier to manage.

The main goal of process documentation is to reduce the amount of system documentation. In order to achieve this, write the minimal documentation plan. List the key contacts, release dates, and your expectations with assumptions.