# 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

* [x] Involve management roles in the documentation process.
* [x] 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.

{% hint style="warning" %}
**The items you have not ticked** are the ones you need to tackle.
{% endhint %}

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

{% hint style="warning" %}
Consider the most critical topic and the most valuable, depending on your product, project, and business objectives.
{% endhint %}

### Blade 4 - Commit to Your Documentation

{% hint style="info" %}
Involve management and technical roles to improve your documentation project.
{% endhint %}

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

{% hint style="info" %}
Setting a reminder in Outlook or using a script or GitHub Actions can be helpful.
{% endhint %}

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