Technical Documentation in Software Development
Technical Documentation in Software Development
Technical Documentation in
Software Development:
Types, Best Practices, and
Tools
Share: Comment:7
Contents
Agile and waterfall approaches.............................................................................................................................................3
Types of documentation.......................................................................................................................................................4
Product: System documentation...........................................................................................................................................6
Product requirement document......................................................................................................................................6
User Experience Design documentation........................................................................................................................9
Software architecture document..................................................................................................................................15
Source code document.................................................................................................................................................16
Quality assurance documentation................................................................................................................................17
Maintenance and help guide........................................................................................................................................18
API documentation......................................................................................................................................................18
Product: User documentation.............................................................................................................................................18
Process Documentation......................................................................................................................................................19
Agile product roadmaps..............................................................................................................................................19
Tools for software documentation......................................................................................................................................22
General purpose tools..................................................................................................................................................22
Markdown editors.......................................................................................................................................................23
Roadmap specific tools...............................................................................................................................................23
Tools for UX documentation.......................................................................................................................................23
Tools for API documentation......................................................................................................................................24
Samples and templates for software documentation.........................................................................................................24
2
Reading time: 18 minutes
Technical documentation in software engineering is the umbrella term that encompasses all written
documents and materials dealing with software product development. All software development
products, whether created by a small team or a large corporation, require some related
documentation. And different types of documents are created through the whole software
development lifecycle (SDLC). Documentation exists to explain product functionality, unify project-
related information, and allow for discussing all significant questions arising between stakeholders
and developers.
Pro
ject documentation by stages and purpose
On top of that, documentation errors can set gaps between the visions of stakeholders and engineers
and, as a result, a proposed solution won’t meet stakeholders expectations. Consequently, managers
should pay a lot of attention to documentation quality.
The Waterfall approach is a linear method with distinct goals for each development phase. Teams
that use waterfall spend a reasonable amount of time on product planning in the early stages of the
project. They create an extensive overview of the main goals and objectives and plan what the
working process will look like. Waterfall teams strive to create detailed documentation before any of
the engineering stages begin. Careful planning works well for projects with little to no changes in
4
progress as it allows for precise budgeting and time estimates. However, waterfall planning has
proven to be ineffective for long-term development as it doesn’t account for possible changes and
contingencies on the go. According to PMI’s 9th Global Project Management Survey, the Agile
approach is used by 71 percent of organizations for their projects.
The agile approach is based on teamwork, close collaboration with customers and stakeholders,
flexibility, and ability to quickly respond to changes. The basic building blocks of agile development
are iterations; each one of them includes planning, analysis, design, development, and testing. The
agile method doesn’t require comprehensive documentation at the beginning. Managers don’t need to
plan much in advance because things can change as the project evolves. This allows for just-in-time
planning. As one of the Agile Manifesto values suggests, putting – “working software over
comprehensive documentation -“, the idea is to produce documentation with information that is
essential to move forward, when it makes the most sense.
Today, agile is the most common practice in software development, so we’ll focus on documentation
practices related to this method.
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.
Product documentation
Process 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. There are two main types of product 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 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.
6
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.
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.
7
8
Here are the main recommendations points to include in your product requirement document:
1. Roles and responsibilities. Start your document with the information about project
participants including a product owner, team members, and stakeholders. These details will
9
clarify responsibilities and communicate the target release goals for each of the team
members.
2. Team goals and business objective. Define the most important goals in a short point form.
3. Background and strategic fit. Provide a brief explanation of the strategic aim of your actions.
Why are you building the product? How do your actions affect product development and align
with the 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. Acceptance criteria. Those are the conditions that indicate a user story is completed. The
main purpose of acceptance criteria is to define a satisfactory result for a usage scenario from
the end-user perspective. Check our dedicated article on acceptance criteria to learn more.
7. User interaction and design. Link the design explorations and wireframes to the page.
8. Questions. As the team solves the problems along the project progression, they inevitably
have many questions arising. A good practice is to record all these questions and track them.
9. 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.
The UX documentation can be divided into stages. The research stage includes:
User personas
User scenario
Scenario map
User story map
UX style guide
10
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.
Source: realtimeboard.com
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
11
arranged and work with each other. But, unlike a UI style guide, UX designers don’t describe the
actual look of the interface.
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
A site/product map is a visual scheme that represents the connection between all pages of a
product. The map helps the whole team visualize the structure of a website or app and the
connections between the pages/functions. Creating a site map is a part of arranging the information
architecture.
12
Source: uxforthemasses.com
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.
13
Source: medium.com
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.
14
Source: gallery.wacom.com
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.
15
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 design document template. Discuss and form a consensus with stakeholders 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.
Diagrammatic representation of the solution. Identify the diagrams that need to be created to help
understand and communicate the structure and design principles.
16
Source: docs.microsoft.com
Source code documents may include but are not limited to the following details:
A test strategy is a document that describes the software testing approach to achieve testing
objectives. This document includes information about team structure and resource needs along with
what should be prioritized during testing. A test strategy is usually static as the strategy is defined for
the entire development scope.
A test plan usually consists of one or two pages and describes what should be tested at a given
moment. This document should contain:
Test checklist is a list of tests that should be run at a particular time. It represents what tests are
completed and how many have failed. All points in the test checklists should be defined correctly. Try
to group test points in the checklists. This approach will help you keep track of them during your work
and not lose any. If it helps testers to check the app correctly, you can add comments to your points
on the list.
18
API documentation
Nearly any product has its APIs or Application Programming Interfaces. Their documentation informs
developers how to effectively use and connect to the required APIs.
API documentation is a deliverable produced by technical writers as tutorials and guides. This type of
documentation should also contain the list of all available APIs with specs for each one.
end-users
system administrators
The documentation created for end-users should explain in the shortest way possible how the
software can help solve their problems. Some parts of user documentation, such as tutorials and
onboarding, in many large customer-based products are replaced with onboarding training.
Nevertheless, there are still complex systems remaining that require documented user guides.
The online form of user documentation requires technical writers to be more imaginative. Online end-
user documentation should include the following sections:
FAQs
Video tutorials
Embedded assistance
Support Portals
In order to provide the best service for end-users, you should collect your customer feedback
continuously. The wiki system is one of the more useful practices. It helps to maintain the existing
documentation. If you use the wiki system you won’t need to export documents to presentable
formats and upload them the servers. You can create your wiki pages using a wiki markup language
and HTML code.
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:
19
Functional description – describes the functionalities of the product. Most parts of this
document are produced after consultation with 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.
There are three types of product roadmaps that are used by Agile product teams:
Strategic roadmap
Technology or IT roadmap
Release plan
A strategic roadmap is a high-level strategic document, that contains overall information on the
project. Strategic roadmaps usually state a vision and long-term goals. In the case of agile product
development, a roadmap can be arranged in themes. Themes are multiple tasks that a team must
complete and are somehow connected. For instance, a theme may sound like “enhance page-loading
speed,” which entails a handful of actions.
Grouping the information around the themes makes a roadmap highly flexible and updatable, which is
a great fit for sprint-based development. The best advice concerning strategic roadmapping is to
include only important information. Otherwise, you risk turning your roadmap into a clumsy scheme,
difficult to both understand and maintain.
Source: productplan.com
21
Source: hutwork.com
A release plan is used to set strict time limits for releases. A release plan should focus on the actual
deadlines without specifying release details.
22
Source: productplan.com
It is highly recommended to use roadmap specific tools to create your own roadmaps. Online tools
like Roadmunk provide various templates for product roadmaps, allow quick editing, and provide easy
sharing across all team members.
Keep in mind, that a roadmap, depending on its type, can be a product document that states
requirements. It also describes the process and guides your team through development.
Atlassian Confluence is the most popular collaborative project tool that has the whole
ecosystem for managing product requirements and writing documentation. Confluence is
known for a stable wiki system and an efficient user story management interface.
23
Markdown editors
As software documentation is easier to be used on the web, it has to be created in a proper format.
That’s why text-based markup languages are used. The most popular one is Markup, which can be
easily converted into HTML, doesn’t require any special knowledge to use it. Markup is used on
GitHub and Reddit, and basically everywhere for web-based documentation. So, here are some
Markdown editors that can be useful for creating documents for your project:
ProductPlan
Aha!
Roadmunk
Roadmap Planner
Basically, all the tools offer free trials and paid plans with differences in templates, numbers of
roadmaps, and persons you can share them with.
Sketch is a simple but powerful vector-based design tool that has a web-application and a Mac
desktop client. Sketch is popular and quite simple, offering enough capabilities for designing
interfaces.
InVision is one of the most popular tools for prototyping. InVision is famous for its collaborative
features and cross-platform capabilities, making it a great tool for designing future interfaces.
UXPin is a Mac and Windows design tools that allows you to build any type of blueprints. You
can also upload your sketches or wireframes from other products and make an interactive
prototype of it.
Adobe XD – where XD stands for experience design. The product is aimed at UX specialists. It
allows designers to create high-fidelity prototypes and share them via the app.
Swagger is a free self-documenting software service designed to create and update RESTful
web services and APIs.
RAML 2 HTML is a simple documentation generator that uses RAML specifications.
Use cross-links
Use cross-links between documents, whether those are product pages or user guides. Proper
navigation through your documentation is important to give the reader the right understanding of a
subject. Such practice can be considered user-flow, but for your project documentation.
Final word
The agile methodology encourages engineering teams to always focus on delivering value to their
customers. This key principle must also be considered in the process of producing software
documentation. Good software documentation should be provided whether it is a software
specifications document for programmers and testers or software manuals for end users.
Comprehensive software documentation is specific, concise, and relevant.
As we have mentioned above, it’s not obligatory to produce the entire set of documents described in
this article. You should rather focus only on those documents that directly help achieve project
objectives.