Types of documentation

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. To achieve them, plenty of documentation types exist.

Adhering to the following classifications.

All software documentation can be divided into two main categories:

 Process documentation

Product documentation describes the product that is being developed and provides

instructions on how to perform various tasks with it. Product documentation can be

broken down into:

 User documentation
System documentation represents documents that describe the system itself and its

parts. It includes requirements documents, design decisions, architecture

descriptions, program source code, and help guides.

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, process. The common examples of process

documentation are project plans, test schedules, reports, standards, meeting notes,

or even business correspondence

The main difference between process and product documentation is that the first one

record the process of development and the second one describes the product that is

being developed.

Product: System documentation

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. So, let’s have a look at the details of the main types.

Requirements document

A requirements document provides information about the 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, 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. Here’s a

look at an example of a one-web-page product-requirements document to understand

various elements that should be included in your PRD. Nevertheless, you should

remember that this isn’t the one and only way to compile this document.

Here are the main recommendations to follow:

1. Roles and responsibilities. Start your document with the information

about project participants including a product owner, team members, and

stakeholders. These details will clarify responsibilities and communicate

the target release goals for each of the team members.

2. Team goals and a business objective. Define the most important goals

in a short point form.

3. Background and strategic fit. Provide a brief explanation about the

strategic aim of your actions. Why are you building the product? How do

your actions affect the product development and align with company’s

goals?

4. Assumptions. Create a list of technical or business assumptions that the

team might have.

5. User Stories. List or link user stories that are required for the project. A

user story is a document written from the point of view of a person using

your software product. The user story is a short description of customer

actions and results they want to achieve.

6. User interaction and design. Link the design explorations and

wireframes to the page.

progression, they inevitably have many questions arising. A good practice

is to record all these questions and track them.

8. Not doing. List the things which you aren’t doing now but plan on doing

soon. Such a list will help you organize your teamwork and prioritize

features.

Make all this information more comprehensive by using the following practices:

 Use links and anchors. They will help you make the document easier to

read and search as readers will be able to comprehend the information

gradually. For instance, you can provide links to customer interviews and

anchors to previous discussions or other external information related to

the project.

 Use diagramming tools to better communicate the problems to your

team. People are more likely to perceive information by looking at the

images than reading an extensive document. Different visual models will

help you to perform this task and outline requirements more effectively.

You can incorporate diagrams into your requirements process using the

following software diagramming tools: Visio, Gliffy, Balsamiq, Axure or

SmartArt in Microsoft Office.

Software architecture document

don’t recommend listing everything, but rather focus on the most relevant and

challenging ones. An effective design and architecture document comprises the

following information sections:

regarding what needs to be covered in the architecture design document before it has

been created and use a defined template to map architectural solutions.

Architecture & Design Principles. Underline the guiding architecture and design

principles with which you will engineer the product. For instance, if you plan to

structure your solution using microservices architecture, don’t forget to specifically

mention this.

User Story description. Connect user stories with associated business processes

and related scenarios. You should try to avoid technical details in this section.

Solution details. Describe the contemplated solution by listing planned services,

modules, components, and their importance.

Diagrammatic representation of the solution. Identify the diagrams that need

to be created to help understand and communicate the structure and design

principles.