Improving Your Development Documentation Project (1 of 3)
Tags: documentation, writing, tutorial
Published: 2023-01-18 17:10:20

> **What this article covers**  
> _First steps on how to improve an existing documentation project._   
> **Tools**  
> _Confluence, GitHub web and desktop version, and MarkdownPad2._  
 
## Introduction     

**Developer Documentation is a curated set of files** describing all the active *workflows*, *setups*, *tools*, *conventions*, *best practices*, and *How-tos* of your software development product. Through this article, I will refer to it as "documentation" or "docs".

Documentation supports your team members in their daily and future developments. It also helps new joiners to reach cruise speed during the onboarding period. *But to do so, your documentation must be up-to-date and well-structured*. 

Keeping the docs up-to-date and in good shape requires resources and dedicated time. Yet often our project time or budget constraints prevent us from taking care of our docs properly. 

This series of articles aims to serve as a documentation improvement guide. 

## Know Your Ground

### Step 1 - Organize Your Improvement Project   

**Developer documentation has to be visible** to increase the chances of success, and to find collaborators (to improve it). To do so, you need a *space* to visualize your project, describe it, and track your progress.  

**Use your teams/company collaboration tool** for that purpose. For this article, we'll be using Confluence.    

  
#### Space Structure  

**The structure of an improvement project may differ** from one project to another. Take the following *space* structure as a reference that you can adapt to your needs (*then iterate!*):    

| Space Name | Page Name | Child Page| Description |  
|------ | ------ | -------| --- |  
| **[Your Documentation Project´s Name]** | | | Name of your documentation project. |  
| | **Overview** | | Explain briefly the What, Why and How of the documentation. |    
| | **Dashboard** | | Centralized page to easily access all project pages. |  
| | **Analysis** | | Media and results of documentation analysis. |  
| | **Roadmap**  | | Visualization of the estimated dates to implement each improvement. |  
| | **Improvement Project** | *Communication Grid* | Contact person by topic. |   
| | | *Improvement Plan* |  Implementation phases and items. |   
| | | *Coordination Meetings* | Grid to align with your manager or collaborators (_Optional_). |   
 


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

* Present it to all your team members, including Product Owners and Scrum Masters.  
* Track and show your progress.  
* Visualize documentation issues/blocking points.  
* Access all your project resources.  

> **Tip:** _Explain how documentation issues negatively impact teams´ performance. It will help Product Owners and Scrum Masters to understand and provide your project with the resources you need._

### Step 2 - Identify Your Documentation Issues  

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

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

In the following table, you can learn a little more about the main documentation issues:

| Documentation Issue | Example |Fix strategy |   
| ------| ----- |------- |   
| **Grammar, spelling, syntax** | Bad gramar, speling and sintax distraks reders from what yo´r tring to say. It alsso give the idea that you doesnt know about it.| Use a text checker to support your writing. Some good options are [Grammarly](https://app.grammarly.com/), [Hemingway](https://hemingwayapp.com/) or [QuillBot](https://quillbot.com/grammar-check).  |  
| **Page structure** | _Coming soon!_| Review your page structure. It shows the logical flow of the information contained according to the objective of the page, for example: *Introduction*, *Prerequisites*, *First Step*, *Working with.../Available Features*. |  
| **Naming** | _Coming soon!_ | Define a naming strategy for page titles, sections and subsections. |  
| **Page elements** |_Coming soon!_ | Standardize the use of the following elements: lists, tables, tabs, notes, collapsible elements and images. |    
| **Text unclear** or **too verbose** | Verbose text:<br> _Selecting this method means the content that is currently in the Awesome server caches is never served. The next time the edge server receives a request for the content, it retrieves the latest version from your origin server._ <br><br>Not verbose:<br> _Using this method prevents the content of the Awesome server cache to be served. Therefore, the Awesome server will retrieve the latest version from your origin server for every new request on the content._| Be concise.|  
| **Random text formatting** | _This is **file.name** with bold format. It is OK. But if I also use a different format for a `file.name` (the same content element), it is more difficult for users to identify what they need and the type of information we are providing._| Standardize the use of bold and italics for files, folder names, code snippets and code elements (functions, objects, methods, parameters, API names, etc.). |  
| **Too many topics on a single page** |A _Getting Started_ page must provide the information and steps required for user to get started. An _About this Chapter_ page must provide introduce the topic, give a context, talk about features briefly.An API reference page (or pages) must focus on those references, not providing getting started information.<br><br>In other words, 1 page, 1 topic. | Stick to "One topic per page". |   
| **Unnecessary screenshots** | _Coming soon!_|Use screenshots or images _ONLY_ when strictly necessary. If you can explain it briefly, do not use screenshots. |  
| **Type of notes** | _Coming soon!_ |Standardize each type of use case for notes (Info, Help, Warning, etc.). |   


**Now we can start to target and record** the issues of our documentation.   

The following table will help you to perform that task:  

| Nav Option | Page | Section | Subsection | Issue | Link |   
| ---------- | ---- | ------- | ---------- | -------| --------- |   
|   **Add nav. option name**   | _Page number_ | _Section name_  | _Subsection name_ | _Issue name_ | ![Link](Link)       |           |  
  
  

**Depending on the size and complexity of your documentation,** targeting these basic issues may take a while.   

Take the chance and join me on the journey to better documentation and improve your documentation project now.

--------------

*To Be Continued…*  

> **What`s Next?**  
> _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._