In this article, we’ll discuss the various types of documents that an organization may need. Each document caters to a particular set of readers and serves specific purposes. 

Other than product documentation intended for customers, organizations may need content that serves the needs of developers, managers, or other internal users. 

The documents discussed in this article have their general structure; however, you can construct your architecture depending on your organization’s needs.

The content types are discussed briefly and the probable author and knowledge source for each are mentioned.

Internal docs

This is the set of documentation that is intended for users who are internal to the organization –  stakeholders, developers, quality teams, or marketing. 

Such documentation is reference material that gives direction to the teams working inside an organization and keeps them synced. They answer all the hows, whys, wheres, and whats of the processes and implementation.

Internal documentation can be of great help to new members of the organization. They can be onboarded easily and help themselves get familiar with the product they are soon going to work on.

Note: This type of documentation may be confidential and should not be shared publicly.

Readme

Readmes are written by developers for other developers and are great documentation to summarize codes in a repository. It explains, briefly, the purpose of codes at a high level and the history of changes made, if any. It can also contain relevant references to other documentation.

It is a good practice that organizations can adopt to make the technical artifacts self-explanatory with little help from others, thus saving time and resources.

Written by – developers/coders

Knowledge source – self

Code comments

Code comments are the few lines of information that developers write for a piece of code. Code comments are helpful in understanding complex codes written by other developers and sometimes by the same developer who wrote them, especially if they are revisiting the code after a long break. It can help them reorient if they feel lost!

Code comments should be crisp and mention very briefly if any change is made to the code- when and why the change was introduced.

Written by – developers/coders

Knowledge source – self

Conceptual documents

As the name suggests, conceptual documents explain the concept behind your product. It answers why the product exists.

Conceptual content explains the functional workflow of the product or a part of the product at a high level. Providing visual aids such as swimlane diagrams, flow charts, or block diagrams can be a good idea for conceptual content.

Written by – technical writers.

Knowledge source – Knowledge transfer from developers, meeting notes, email threads, and design diagrams.

Specification / Requirement documentation

Software Requirement Specification (SRS or SRD) is a document that serves as the blueprint for the software that is to be developed. It defines the scope of the project and the customer’s expectations. All the functional requirements, dependencies, assumptions, security requirements, safety, and quality requirements are mentioned here in detail.

This is the document that the developers, stakeholders, and QA team fall back on, to fetch any details about the product. This document helps the developers to plan the development of the product. The QA team can use it to prepare their test plan.

Written by – Technical writers can liaison with stakeholders/business analysts to write this document.

Knowledge source –  Meeting notes, recordings, email threads, and inputs from stakeholders/business analysts.

Friction logs

You have to get into the user’s shoes to write friction logs. This document is written to find out friction areas in the product flows to improve user experience and make the product user-friendly. 

Friction loggers can pick up scenarios and try to trace the flow as a user and write the friction points. For example, the Sign-up scenario.

‘Friction’ points are the pain areas in the product flow, which may lead to confusion and frustration among the users.

‘Wow,’ points are those areas in the flow where the users sail smoothly in the product flow.

Note: You can use terms of your choice for  ‘Friction’ and ‘wow’. This is just for reporting purposes.

You should write friction logs for scenarios that users are most likely to use. This ensures the most used scenarios are frictionless, resulting in happy customers.

An ideal friction report (friction log) resembles bug reproduction steps with the logger’s comments after each step. The comment describes the feeling of the user while performing the steps. These comments can be colored green or red. Red indicates “friction” and green indicates “wow” areas.

Written by – Anyone having knowledge of UI/UX and information architecture.

Knowledge source –  The logger can refer to product documents to learn about the various scenarios and flows.

External docs

This is a documentation set that organizations have on a public platform for their customers. They help the users to understand the product, get started with it, and use it. Such documents, if properly written, ensure fewer calls to customer care and greater trust in the product.

External documentation should be regularly updated along with the product. No outdated information should exist on the customer-facing documentation.

API document

API documentation helps external developers integrate your service with your application. It is extremely important content from a business perspective. Great APIs with equally great documentation drive sales and can increase cash flow into the organization.

API documentation tells you how to use the API and how to integrate the API with your system. It can also tell you about the API versions and the changes to an API.

There are numerous API documentation and testing tools available in the market. You can also use your own template to write API documentation using Google Docs or MS Word.

API documentation knowledge and experience give technical writers an extra edge.

Written by: Technical writers

Knowledge source: Developers

Product manuals/guides

These are the primary documents that help the end user learn about the product. They are the product knowledge base. Such documents usually have a large number of pages. They may not help you quickly solve an issue with the product but are a great source if you want in-depth knowledge about the product.

Product manuals can be used to prepare training materials for organizations. An ideal product manual has everything from the simplest (For example, login information) to the most advanced information (for example, creating and tracking work orders) documented.

Written by: Technical writers

Knowledge source: Developers, stakeholders, test cases, meeting notes

Manual v/s Guide

Manual and guide are interchangeably used for documents. Following are the two notable differences:

• A manual is a text document (digital or printed), while a guide can be a text or a video.
• Guides can be a short text or single-page pictorial representation of a process, while a manual is usually in the form of a booklet.

Quick start guide

These are secondary documents derived from the product manuals.

A quick start guide is usually a short guide that helps you get started with using a product or an application. It is usually on a single page but can have a few additional pages.

Datasheets can come bundled with a quick start guide to provide quick technical reference to the user if required.

Written by: Technical writers

Knowledge source: Product manuals

How to guides

Unlike user manuals, a quick start guide does not provide in-depth knowledge about the product but it solves a particular problem of the user.

For example, how to install the software on a Mac machine?

Ideally, How-to guides should provide solutions to one single problem or a single set of problems. 

For example, how to implement Google SSO for your web application?

Implementing Google SSO involves certain configurations on the Google side and the native system. Therefore, all of these form a set of procedures that solves a single problem.

Written by: Technical writers

Knowledge source: Product manuals

References

References are content that may occur independently or can be a topic in other guides.

• When they occur as a topic inside other guides, they tell you about related content that may interest you.
• When they occur independently, they are usually in the form of FAQs, glossaries, and troubleshooting guides.

Written by: Technical writers

Knowledge source: Product manuals

Conclusion

These technical documents form the basic structure of a company. It helps a business to run smoothly with seamless internal communication. Hence, if you were confused about how to streamline your organization, we hope this blog will help you.

You may get in touch with us at info@bigsteptech.com for further queries. Let’s create the future together!