# Part 1 of 3

## Improving Your Developer Documentation Project (1 of 3)

> **What this article covers**\
> \&#xNAN;*First steps on how to improve your developer documentation project.*\
> **Tools**\
> \&#xNAN;*Confluence, GitHub (web and desktop versions), and MarkdownPad2.*

## Introduction

**Developer Documentation is a curated set of files** organizing and disclosing all the information your product and platform users need to succeed, for example:

* Basic setups
* Style guides and best practices
* Security configurations
* Overview information
* Getting started and how-tos
* Reference guides
* FAQ and troubleshooting pages

**Documentation supports your team members in their daily and future developments and helps new joiners** reach cruise speed during the onboarding period. *But to do so, you need your docs to be* *in good shape,* resources, and dedicated time.

In the following sections, you will find a concise description of some steps you can take to start improving your documentation project.

## First Steps

**We can improve an existing documentation project from many perspectives**. The following steps represent the approach I've found more efficient in the middle and long term because it helps us to create *documentation awareness* (steps 1 and 2) and aligns *user feedback* (step 3) with our observations and ideas from the beginning.

### Step 1 - Create Documentation Awareness

**Creating documentation awareness is the continuous process by which we communicate the existence and use** of the documentation aiming to:

* *Increase successful product development.*
* *Resources' usage efficiency.*
* *Cross-team collaboration.*

**To communicate the existence and importance of any documentation project,** we can use the following communication plan:

| Topic             | Actions                                                                                                                                                                                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Communication** | <ul><li>Communicate the need for feedback and collaboration to all management roles and teams using it.</li><li>Create two dedicated chat channels for documentation updates and documentation support topics.</li><li>Shared meaningful and frequent documentation updates in the main chat channels.</li></ul> |
| **Training**      | <ul><li>Participate in onboarding processes.</li><li><p>Participate in cross-team meetings with documentation topics, for example:</p><ul><li>Good practices</li><li>Basic style guide</li><li>Effective communication</li><li>Giving feedback</li><li>Information Architecture</li></ul></li></ul>              |
| **Feedback**      | <ul><li>Create a survey to gather user feedback about different documentation aspects.</li><li>Run the user feedback once a year (at least).</li></ul>                                                                                                                                                           |

**Communication is a continuous and daily task** that requires *active listening and empathy.* Save some time every week to review all the feedback, and make sure you help Product Owners, Scrum Masters, and similar leading roles to understand the importance and needs of having an efficient documentation.

### Step 2 - Create Your Improvement Project

**Your developer documentation is a product** and, as such, your priority is to make it a successful one.\
A product is successful if it helps its users to succeed in their tasks, and does it efficiently. To manage our documentation as a product we need a *dedicated space* (company Confluence, blog, etc.).

**Having a dedicated space for our documentation project** supports the efforts of increasing the *documentation visibility and awareness*. As a side effect, it helps to radiate documentation good practices and style guide for other teams to learn and use.

#### **Space Structure**

**The structure of any project may differ** depending on your needs. Take the following *space* structure as a reference that you can adapt to your needs:

<table><thead><tr><th width="214">Space Name</th><th width="138">Main Section</th><th width="187">Child Section</th><th>Description</th></tr></thead><tbody><tr><td><strong>[Your Documentation Project´s Name]</strong></td><td><em>N/A</em></td><td><em>N/A</em></td><td>Name of your documentation project.</td></tr><tr><td></td><td><strong>Overview</strong></td><td></td><td>Explain briefly the What, Why and How of the documentation.</td></tr><tr><td></td><td><strong>Dashboard</strong></td><td></td><td>Centralized page to easily access all project pages.</td></tr><tr><td></td><td><strong>Analysis</strong></td><td></td><td>Media and results of documentation analysis.</td></tr><tr><td></td><td><strong>Roadmap</strong></td><td></td><td>Visualization of the estimated dates to implement each improvement.</td></tr><tr><td></td><td><strong>Project Development</strong></td><td><em>Communication Grid</em></td><td>Contact person by topic.</td></tr><tr><td></td><td></td><td><em>Improvement Plan</em></td><td>Implementation phases and items.</td></tr><tr><td></td><td></td><td><em>Coordination Meetings</em></td><td>Grid to align with your manager or collaborators (<em>Optional</em>).</td></tr></tbody></table>

**Once your improvement project space is set up,** you are ready to:

* Make an official presentation (remember to invite leading roles).
* Track your progress and documentation issues/blocking points.
* Centralize all your project resources.

### Step 3 - Identify Your Documentation Issues

**Identifying your documentation issues means** spotting all the types of issues living among your docs. Some common documentation issues are the following:

* Grammar, spelling, and syntax errors.
* Confusing/Not logical page structure.
* Unclear/Verbose text.

**For each type of documentation issue**, we can apply a specific fix strategy as shown in the following table:

<table><thead><tr><th width="287">Documentation Issue</th><th>Fix strategy</th></tr></thead><tbody><tr><td><strong>Grammar, spelling, syntax</strong></td><td>Use a text checker to support your writing. Some good options are <a href="https://app.grammarly.com/">Grammarly</a>, <a href="https://hemingwayapp.com/">Hemingway</a> or <a href="https://quillbot.com/grammar-check">QuillBot</a> or<a href="https://vale.sh/"> Vale</a>.</td></tr><tr><td><strong>Page structure</strong></td><td><ul><li>Make sure you present the information in the right and logical order for your user.</li><li>Use or create templates for your documentation. Templates make it easy for user to find what they need.</li></ul></td></tr><tr><td><strong>Naming</strong></td><td><ul><li>Define a naming strategy for page titles, sections and subsections.</li><li>Implement your strategy.</li></ul></td></tr><tr><td><strong>Page elements</strong></td><td><p>Standardize the use of the following elements:</p><ul><li>lists and tables,</li><li>tabs,</li><li>notes and collapsable elements,</li><li>image size.</li></ul></td></tr><tr><td><strong>Text unclear</strong> or <strong>too verbose</strong></td><td><ul><li>Stick to 1 topic (idea) per page.</li><li>Ensure your page provides the exact amount of information the user needs.</li><li>Be concise in your writing.</li></ul></td></tr><tr><td><strong>Random text formatting</strong></td><td><p>Create a basic style guide for text formatting. For example:</p><ul><li><p><strong>bold</strong> for:</p><ul><li>the first sentence of a paragraph to support page scanning (and if meaningfull),</li><li>text in the first column of a table,</li></ul></li><li><em>italics</em> for files and folder names,</li><li>different font for code snippets and code elements.</li></ul></td></tr><tr><td><strong>Too many topics on a single page</strong></td><td>Stick to "One topic per page". Each page should provie one answer only to the question "What is this pages about?".</td></tr><tr><td><strong>Unnecessary screenshots</strong></td><td>Use screenshots or images <em>ONLY</em> when strictly necessary. If you can explain it briefly, do not use screenshots.</td></tr><tr><td><strong>Type of notes</strong></td><td>Standardize each type of use case for notes (Info, Help, Warning, etc.).</td></tr></tbody></table>

> **What\`s Next?**\
> \&#xNAN;*In the next article, we will describe how to run a user survey to gather useful feedback from your users/readers. This invaluable feedback will help us prioritize the documentation issues to fix first.*