Documentation Project Swiss-Knife

What this article covers &#xNAN;Basic ideas to develop and manage a documentation project successfully. Tools &#xNAN;N/A.

Overview

Product development benefits from having effective documentation. A documentation set is effective when the content that is easy to find, easy to understand, and easy to act upon, while being comprehensive across all the known contexts of use.

Budget constraints too often get in the way of having and effective documentation, an obstacle to hire the dedicated role we need: a technical writer. This article offers a practical Swiss knife to help you manage and improve your documentation project, even without a dedicated technical writer.

Prerequisites

• Involve management roles in the documentation process.

• Save a small amount of time for documentation work.

Technical Documentation Swiss-Knife

The Swiss-knife for managing and improving documentation projects includes the following basic ideas (blades):

1. Know your ground.

2. Know your documentation needs.

3. Prioritize and plan.

4. Commit to your documentation.

Blade 1 - Know Your Ground

Know your ground before taking any further step. This means:

• Identifying deficiencies in your documentation.

• Determining what is preventing it from being useful, and effective.

Consider the following checklist to analyze the current status of your documentation:

• My documentation provides content for all the topics my users need to know.

• My documentation pages tell users:

• What is the page about

• What they can do

• How to do it

• Who to ask for help

• My documentation informs about prerequisites (if any).

• My documentation provides all the required information for the specific user case/type of page.

• My documentation is clear, specific and concise (no verbose).

• There is a clear workflow to gather feedback, review and update the documentation.

• My documentation architecture mirrors the workflow of regular users.

The items you have not ticked are the ones you need to tackle.

Knowing your ground can be daunting. But despair do not! Be patient and take small steps. Then iterate!

Blade 2 - Know Your Documentation Needs

If the Oracle of Delphi managed documentation, it might have said:

"Know your documentation needs."

Knowing your documentation needs helps you to contextualize the insights you've gained from the previous checklist.

To identify your documentation needs, answer the following questions:

• Do I have a clear and coherent writing style for my documentation?

• Do I need to increase clarity?

• Do I just need to reduce verbosity?

• How often do I need to review and update my documentation?

• Who can review the documentation updates?

• Who can ensure the correctness of the documentation?

• Do I have communication channels for my users to provide feedback?

• What is the minimum viable and valuable documentation for my project/product?

Once you've answered these questions, you'll be ready to prioritize and plan your documentation effort.

Blade 3 - Prioritize and Plan your Documentation Effort

Every project is different, but understanding where your documentation is and its needs increases the chances of success. With these new insights, you can now prioritize and plan. To prioritize your efforts, identify the most critical topic/issue, and the most valuable one. Then decide where to start based on your product's priorities and needs.

Starting with the most critical topic means addressing the topic/issue which is to develop your product.

Starting with the most valuable topic means addressing the topic that offers the most value to your customer or project.

Once you've prioritized, create a roadmap or backlog to track and update your progress.

Consider the most critical topic and the most valuable, depending on your product, project, and business objectives.

Blade 4 - Commit to Your Documentation

Involve management and technical roles to improve your documentation project.

Now that you know your ground and needs, and have prioritized, it is time to commit to your documentation. This commitment is key to improving and managing your documentation actively and regularly.

To support your commitment, consider these tips:

1. Allocate time for documentation efforts (every week, ideally).

2. Create an automatic reminder (Outlook, Calendar, GitHub Actions, Slack, Teams, etc.).

3. Involve other team members.

4. Inform management about the importance of the documentation.

Setting a reminder in Outlook or using a script or GitHub Actions can be helpful.

Bonus: Basic Style Guide

If you are reading this article, you probably don't have much time to search, read, and implement style guides and good practices. Don't worry, here are some fundamental documentation writing tips you can learn and apply quickly:

Topic	Description
Text Formatting	Bold - Apply bold to the first meaningfull part of a the first sentence of a paragraph to support page scanning. Italics - Apply italics to file and folder names, and to highlight text segment inside a paragraph. code - Apply `` for code snippets and cli commands.
Page Content	Provide an introduction for every page. Develop 1 single topic/idea per page and section. Provide clear and concise titles.
Writing	Provide just: The right information In the right context In the right order
Quality	Use a grammar check in your IDE (Have you checked Vale?). Use a link checker in your IDE. Create a checklist to review your content.