Technical Writing – How to Write Software Documentation

In this post, I will share the notes I took from the online course “Technical Writing: How to Write Software Documentation” by Jordan Stanchev. I purchased this course to apply what I learned and to improve the quality of documentation in my future blog posts. Here is what I learned from the course:

In technical documentation, we aim to explain what a product or service is developed for and what it offers.

Steps of Technical Documentation

• Planning

Creating a plan for what you will do and how you will do it.

• Preparing

Drafting the first set of information.

• Creating

Turning drafts into actual content.

• Organizing and Structuring

Organizing the content based on how the user will interact with it.

• Classifying

After organizing the content, use metadata, labels, and tags to classify it. This makes searching and finding information easier for the end user.

• Publishing

Sharing the prepared content with end users.

• Maintaining

Keeping the published content up to date and maintaining it in sync with product or service updates.

Always keep in mind who the documentation is being prepared for.

Common Types of Documentation

Functional Documentation

• Suitable for starting with a new product.
• Explains what you see in front of you.
• Helps you navigate the product.
• Often used for physical products.

Source: Cefla Finishing

One of the biggest mistakes when writing functional documentation is thinking that it is sufficient on its own. If only functional documentation is provided, it will be unhelpful for the end user. Software documentation usually assumes that the user already knows a few things. Of course, introductory documentation is important, but it is not the main form of documentation.

Strategies for Writing Functional Documentation

1. Start with the home screen.
2. Explain each page and its purpose.
3. Tell users what they are seeing on the screen (giving too many details at once can cause confusion).
4. Organize content based on the visual order of the interface.

Task-Oriented Documentation

• Suitable for advanced usage of a product.
• Barely explains what is in front of the user; instead, it shows how to achieve a specific outcome.
• Helps users navigate through one or multiple related products.
• Commonly used for software products.
• Guides users step-by-step through a process.

A user won’t search for “what does the button I see on the screen do.” That’s meaningless from the user’s perspective. Users come to your documentation to accomplish something, to solve a specific problem in the software. This is where task-oriented documentation comes into play. Your documentation should help users find the answers they are looking for. The goal is not to explain how to use the software but how to perform the necessary tasks.

Strategy for Writing Task-Oriented Documentation

1. Identify the tasks that customers need to perform.
2. Order these tasks logically.
3. Add the supporting concepts and information users need to know.
4. Once users know the product better, provide additional reference materials to assist them.

If a software concept can be explained visually, use appropriate visuals. Today, many users find long documents boring and tend to skim or skip text entirely. Therefore, avoid long blocks of text.

In Summary:

• Research and gather information
• Start writing all the information – “Information dump”
• Begin structuring and organizing the content – “Draft”
• Present it to stakeholders and collect feedback
• Incorporate feedback into the documentation
• Prepare the final delivery
• Publish it
• Gather customer feedback and keep the documentation up to date