Product teams and software teams both share a common bugbear: documentation.
Product documentation refers to user-facing manuals and guides which explain the workflow and user interface of a product. How can the average user be productive with this product? In this sense, product documentation could be used for software products.
Software documentation refers to the underlying technologies, prerequisites, and configurable attributes of a software product. How do IT administrators configure, monitor, host, and deploy the software product for users? This type of documentation is important, especially when multiple versions or branches are added into the mix.
In a sense, product documentation is like teaching someone how to drive a car. The wheel turns the car, the accelerator pedal moves the car, the brake pedal stops the car. Software documentation teaches someone how the car works. The wheel is connected to the front axle which turns the front tires to alter the course of travel; the accelerator increases airflow to the engine which draws in more fuel, generating torque and horsepower.
Both documentation types are important. One educates users, and one educates administrators and developers. It’s great showing people how to drive a car, but if nobody knows how the car works, what happens when the car breaks down?
Minor Differences Between Product and Software Documentation¶
There are minor differences to be aware of with product and software documentation:
Software and Product Documentation: Target Audience and Persona¶
Product documentation caters to a single audience; the user. It assumes the user has no technical knowledge, communicating in plain English with minimal jargon. Much like a technical apprenticeship versus a university degree, it educates people on how to do things, with less focus on theoretical or conceptual knowledge.
Software documentation is targeted to IT administrators, engineers, and developers. It covers the design and architecture of software, command line setup instructions, API and integration support, data management and reporting, network topology – basically the cogs that make the machine work. These documents form a single-source-of-truth (SSOT) that IT personnel can refer to when monitoring and troubleshooting the software application.
Software and Product Documentation: Update Frequencies¶
Software documentation must be consistently updated as new commits are merged into the main release channel. The software documentation must highlight new functions and commands, and deprecate old features. New or changing dependencies should be documented, and feature support across all target platforms should be clarified – such as one feature working on Windows, but not Linux.
Product documentation only needs updating when underlying software edits trigger a change in workflow or usability. A developer changes the code for a payment gateway, but the payment process for users stays the same, so no updates are needed.
This shows a natural hierarchy for software product documentation. Technical software documentation forms the foundation, and subsequent product documentation is based on this foundation. Therefore, the focus should be on making great software documentation, as it breeds even greater product documentation.
Example Formatting Frameworks for Product and Software Documentation¶
A piece of product documentation could follow this framework:
-
Product Name
-
Overview of Product Purpose
-
Setup Guide
-
Feature 1 Explanation and Images
-
Feature 2 Explanation and Images
-
Customer Support Links
Similarly, a piece of software documentation could follow this framework:
-
Software Name
-
Overview of Software Purpose
-
Software Dependencies
-
Installation Guide
-
Function 1 Explanation and Images
-
Function 2 Explanation and Images
-
Technical Support Links
Clearly, these two documentation types are closely related to each other and follow a similar structure. This means that product and software teams have a lot to learn from one another, and a lot of potential when working collaboratively on documentation.
Product and Software Documentation Teams Can Complement Each Other¶
There are stark similarities between product and software documentation. This presents the question: can product and software teams work together?
Yes, they can, and they should!
Software teams understand the technical jargon and underlying technologies. Product teams understand what users see, want, and need; the user experience. Software documentation writers can provide detailed technical information, and product documentation writers can dilute the technical details for consumption by a layperson audience.
Imagine trying to explain something in laypersons terms, without having the high-level understanding needed to formulate something a layperson would understand. That is what happens when product documentation is created before software documentation.
What is quantum mechanics? Schrodinger’s cat is probably the first thought in your head! But what does quantum mechanics have to do with cats? To the user, it’s not important. To a physicist, it means everything.
Start With Software Documentation, End With Better Product Documentation in Docsie¶
To conclude, there are many benefits when using software documentation as a template for subsequent product documentation. Software documentation should act as a single-source-of-truth for IT personnel and product documentation writers. After it is written, product documentation writers will have the clarity and understanding to simplify and share user-friendly knowledge with customers, with technical guidance for proofreading and quality assurance.
Simply, by starting with great software documentation, your writers can craft even better product documentation!
Start crafting documentation that helps your customers do more. Sign up for our Startup plan (forever free!) and deliver documentation delight with Docsie!