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

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:

Space Name	Main Section	Child Section	Description
[Your Documentation Project´s Name]	N/A	N/A	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.
	Project Development	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:

• 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:

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

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.