Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.

2020 22:11

Menu

Last Updated: 26 Mar, 2019

Technical Documentation in Software

Development: Types, Best Practices, and Tools
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 di!erent 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 signi"cant questions arising between stakeholders
and developers.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 1 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

Project 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.

Agile and waterfall approaches

The documentation types that the team produces and its scope depending on the software
development approach that was chosen. There are two main ones: agile and waterfall. Each is
unique in terms of accompanying documentation.

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 progress as it allows for precise budgeting and time estimates. However, waterfall
planning has proven to be ine!ective 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.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 2 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

Agile development cycle scheme

The agile approach is based on teamwork, close collaboration with customers and stakeholders,
#exibility, 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 e!ective 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 classi"cations.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 3 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

Software documentation most commonly used in Agile projects

All software documentation can be divided into two main categories:

· 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 speci"cations, 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.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 4 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

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 di!erence between process and product documentation is that the "rst 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, veri"cation 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.

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. 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.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 5 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 6 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

Technical documentation example: One web-page software requirements document created by using
Atlassian Con!uence, the content collaboration software

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
clarify responsibilities and communicate the target release goals for each of the team members.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 7 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

2. Team goals and business objective. De"ne the most important goals in a short point form.
3. Background and strategic !t. Provide a brief explanation of the strategic aim of your actions.
Why are you building the product? How do your actions a!ect 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 de"ne 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.
Di!erent visual models will help you to perform this task and outline requirements more
e!ectively. You can incorporate diagrams into your requirements process using the following
software diagramming tools: Visio, Gli!y, Balsamiq, Axure or SmartArt in Microsoft O$ce.

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:

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 8 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

· 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
speci"c 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.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 9 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

An example of a user story map broken down into releases

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, de"ning the rules of how they should
be 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 #ow schemes or user journey

· Usability testing reports

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 10 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

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.

Site map structure example

Source: uxforthemasses.com

User "ow 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 #ow 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.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 11 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

Job search application user !ow scheme

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.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 12 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

Wireframe example for Peekaboo mobile app

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 "nal product design.

A prototype is a mock-up that you can interact with: click some buttons, navigate between
di!erent 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.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 13 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

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 document

Software architecture design documents include the main architectural decisions which are made
by solution architect. We don’t recommend listing everything, but rather focus on the most
relevant and challenging ones. An e!ective design and architecture document comprises the
following information sections:

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 de"ned 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 speci"cally 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.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 14 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

Azure web application architecture diagram

Source: docs.microsoft.com

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

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 15 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

· Other patterns and principles

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

Quality assurance documentation

There are di!erent types of testing documents in agile. We have outlined the most common:

· Quality management plan

· Test strategy

· Test plan

· Test case speci"cations

· Test checklists

A quality management plan is an analog of a requirement document dedicated to testing. This

document sets the required standard for product quality and describes the methods to achieve
this level. The plan helps to schedule QA tasks and manage testing activity for product managers,
but, it is mainly used for large-scale projects.

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
de"ned 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:

· The list of features to be tested

· Testing methods

· Timeframes

· Roles and responsibilities (e.g. unit tests may be performed either by the QA team or by
engineers)

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 16 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

A test case speci!cations document is a set of detailed actions to verify each feature or
functionality of a product. Usually, a QA team writes a separate speci"cations document for each
product unit. Test case speci"cations are based on the approach outlined in the test plan. A good
practice is to simplify speci"cations description and avoid test case repetitions.

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 de"ned 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.

Maintenance and help guide

This document should describe known problems with the system and their solutions. It also
should represent the dependencies between di!erent parts of the system.

API documentation
Nearly any product has its APIs or Application Programming Interfaces. Their documentation
informs developers how to e!ectively 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.

Product: User documentation

As the name suggests, user documentation is created for product users. However, their categories
may also di!er. So, you should structure user documentation according to the di!erent user tasks
and di!erent levels of their experience. Generally, user documentation is aimed at two large
categories:

· 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.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 17 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

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:

· 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 di!erent types of behaviors of the system in di!erent
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 re#ect how time and human resources were used during
development. They can be generated on a daily, weekly, or monthly basis. Consult our article on

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 18 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

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 speci"c 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 speci"c 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.

Agile product roadmaps

Product roadmaps are used in Agile software development to document vision, strategy, and
overall goals of the project. Roadmaps are used as process documents to keep the course of
development in sync with initial goals. Depending on the type of product roadmap, it can express
high-level objectives, prioritization of tasks, the sprint timeline, or low-level details.

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

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 19 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

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 #exible and updatable,
which is a great "t 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, di$cult to both understand and maintain.

Strategic software product roadmap example

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 20 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

Source: productplan.com

A technology roadmap or IT roadmap is a low-level document that describes technical

requirements and the means of technology implementation. IT roadmaps are quite detailed. They
contain the information on each deliverable, explaining the reason for such a decision.

Technology roadmap example

Source: hutwork.com

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 21 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

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.

Release plan example

Source: productplan.com

It is highly recommended to use roadmap speci"c tools to create your own roadmaps. Online tools
like Roadmunk provide various templates for product roadmaps, allow quick editing, and provide

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 22 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

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.

Tools for software documentation

General purpose tools
There are countless collaborative tools for software development teams. Those can help to state
requirements, share information, and document features and processes:

· Atlassian Con#uence is the most popular collaborative project tool that has the whole
ecosystem for managing product requirements and writing documentation. Con#uence is
known for a stable wiki system and an e$cient user story management interface.

· Document 360 is a self-service knowledge base/software documentation platform designed for

Software-as-a-Service products.

· ai is a tool for collaborative documentation creation, storing, data sharing, and using a wiki
system. The documentation is interactive, meaning that developers can embed blocks or
snippets of code right into the document and share it in one click. Once you "nish editing your
documentation, you can save it in PDF or markdown format, and post on any other platform.

· Github needs no introduction, except for those who want to use it for software documentation.
It provides you with its own wiki system and allows for converting your documentation into a
compelling website showcases.

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:

· Visual Studio Code

· Typora

· iA writer

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 23 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

· Quiver

Roadmap specific tools

It’s a good practice to use roadmap speci"c tools, as they allow you to share the information
quickly, update timelines or themes, add new points, and edit the whole structure. Most
roadmapping tools provide templates for di!erent roadmaps to let you start working with this
document right away.

· ProductPlan

· Aha!

· Roadmunk

· Roadmap Planner

Basically, all the tools o!er free trials and paid plans with di!erences in templates, numbers of
roadmaps, and persons you can share them with.

Tools for UX documentation

The most popular tools for user experience design are prototyping tools that help create sketches,
mock-ups, wireframes, and interactive prototypes:

· 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, o!ering 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-"delity prototypes and share them via the app.

Tools for API documentation

The process of creating API documentation is most often automated. Programmers or tech writers

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 24 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

may write the documentation manually or use API documentation generators:

· 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 speci"cations.

Samples and templates for software documentation

If your team is struggling to "nd a qualitative template for some type of software documentation,
here are sources of documentation templates:

· umkc.edu – a list of di!erent testing, architectural, requirement documents, and plans.

· Atlassian Con#uence Templates. Atlassian provides general-purpose project documentation

templates with their product out of the box.

· strongqa.com – documentation templates for quality assurance specialists. These include testing
checklists, smoke testing templates, test plans, and more.

· ReadySET is a large library of software documentation templates in HTML that include planning
documents, architecture, design, requirements, testing, and many more.

· ReadTheDocs is an all-in-one template made with ReadTheDocs platform, providing instructions

on writing each type of document you may need, from architecture and UML diagrams to user
manuals.

How to write software documentation: general advice

There are several common practices that should be applied to all the major types of
documentation we discussed above:

Write just enough documentation

You should "nd a balance between no documentation and excessive documentation. Poor
documentation causes many errors and reduces e$ciency in every phase of software product
development. At the same time, there is no need to provide an abundance of documentation and
to repeat information in several papers. Only the most necessary and relevant information should
be documented. Finding the right balance also entails analyzing the project’s complexity before
development starts.

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 25 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

Documentation is an ongoing process

This means that you should keep your documentation up-to-date. It is very important as
documents that aren’t current automatically lose their value. If requirements change during
software development, you need to ensure that there’s a systematic documentation update
process that includes information that has changed. You can use automatic version control to
manage this process more e$ciently.

Documentation is the collaborative effort of all team members

The agile method is based on a collaborative approach to creating documentation. If you want to
achieve e$ciency, interview programmers and testers about the functionalities of the software.
Then, after you have written some documentation, share it with your team and get feedback. To
get more information try to comment, ask questions, and encourage others to share their
thoughts and ideas. Every team member can make a valuable contribution to the documents you
produce.

Hire a tech writer

If you can, it worth hiring an employee who will take care of your documentation. The person who
generally does this job is called a technical writer. A tech writer with an engineering background
can gather information from developers without requiring someone to explain in detail what is
going on. It’s also worth embedding a technical writer as a team member, locating this person in
the same o$ce to establish close cooperation. He or she will be able to take part in regular
meetings and discussions.

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-#ow, but for your project documentation.

Don’t ignore glossaries

Documentation can be dedicated to internal or external usage. In the case of external documents,
it is better to provide a clear explanation of every term, and its speci"c meaning in the project.
Documentation should communicate ideas in clear language to set lingua franca between
stakeholders, internal members, and users.

Final word
https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 26 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

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
speci"cations document for programmers and testers or software manuals for end users.
Comprehensive software documentation is speci"c, 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.

Subscribe to our newsletter

Enter your email Subscribe

Yes, I understand and agree to the Privacy Policy

14 Comments

Further Reading

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 27 of 28
Technical Documentation in Software Development: Types and Tools | AltexSoft 22.10.2020 22:11

WHITEPAPER

WHITEPAPER
Estimating
Agile Project Software
Management: Engineering
Best Practices Effort: Project
and and Product
Methodologies Development
Agile Software Approach
Development
Metrics and KPIs
that Help
Optimize Product
Delivery

https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/ Page 28 of 28