Improving Your Development Documentation Project (1 of 3)

Improving Your Development Documentation Project (1 of 3)

Javier Hernandez · January 18, 2023

What this article covers
First steps on how to improve an existing documentation project.

Tools
Confluence, GitHub web and desktop versions, 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, keeping a space to visualize, describe and track your improvement project is a useful idea.

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 NamePage NameChild PageDescription
[Your Documentation Project´s Name]Name of your documentation project.
OverviewExplain briefly the What, Why and How of the documentation.
DashboardCentralized page to easily access all project pages.
AnalysisMedia and results of documentation analysis.
RoadmapVisualization of the estimated dates to implement each improvement.
Improvement ProjectCommunication GridContact person by topic.
Improvement PlanImplementation phases and items.
Coordination MeetingsGrid 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 IssueFix strategy
Grammar, spelling, syntaxUse a text checker to support your writing. Some good options are Grammarly, Hemingway or QuillBot.
Page structureReview 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.
NamingDefine a naming strategy for page titles, sections and subsections.
Page elementsStandardize the use of the following elements: lists, tables, tabs, notes, collapsible elements and images.
Text unclear or too verboseBe concise.
Random text formattingStandardize 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 pageStick to "One topic per page".
Unnecessary screenshotsUse screenshots or images ONLY when strictly necessary. If you can explain it briefly, do not use screenshots.
Type of notesStandardize 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 OptionPageSectionSubsectionIssueLink
Add nav. option namePage numberSection nameSubsection nameIssue name

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 second article (2 of 3 article), we 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.


Javier Hernandez

Technical Writer @ Lisbon