DEV Community: Javier Hernández

Improving an Existing Documentation Project (3 of 3)

Javier Hernández — Fri, 17 Nov 2023 22:35:47 +0000

What this article covers

Analysis of the results of the survey and the derived improvement actions.

Tools

MS Forms and Excel.

Actioning Your Users' Feedback

Now that we know the current status of our documentation better (See part 1) and we have gathered feedback from our users (See part 2), it is time to analyze the results of our survey. Based on that, we should then find out which improvement actions we can extract from it.

For this article, I'm providing some screenshots of the results of a real developer documentation survey.

Let the fun begin!

Analyzing the Results

To analyze the results of the our survey we will group the questions under the following categories:

Awareness - Are users aware of your documentation?
Frequency of use.
Search and page access behavior - How our users search and access our documentation pages.
Page design - Does our page design meet the needs of our users?
Next steps (According to our users).
General perception.
Other comments.

Grouping our questions helps us to identify the type of issues impacting our documentation and the domain of the solution to implement.

Results Categories

The following table shows the screenshots of the survey results, for each category, and some quick thoughts about them:

Category	Results	Quick Thoughts
Awareness		Our documentation is known but there is still space to reach more readers/users.
Frequency of use		Our documentation is being used. Yay!
Search and page access behavior		If a great number of users do CTRL+F to find content on a page, we should review our page design to ensure we are supporting that behaviour.
Page design		Even if the majority of our users prefer the content being gradually reveal, a great deal of our users prefer the content being shown all at once. Let's find a balance!
Next steps (According to our users)		Keeping our documentation up-to-date requires finding a cross-team collaboration strategy to involve all the required Subject Matter Experts (SME).
General perception		Our documentation is perceive as useful. What about opening the door more more content?

What to Do Next?

To decide what to do next keep in mind the current state and the needs (priorities) of our users. From this perspective, you can identify which improvement actions will have the highest impact on your users more accurately.

Once you have done that, plan accordingly.

When evaluating the current state of our documentation, you may target some hot potatoes. In this case, do some firefighting first and reduce the biggest pain.

If we don't have any firefighting to do, talk to your manager roles (Product Owner, Scrum Master, Lead Link, etc) or your customer/user insights roles/team to:

Share the survey results.
Explain and discuss your ideas.
Know their thoughts and perspective.

Involving management and customer/user insights roles increases the awareness of your documentation project, and reinforces the following idea:

Improving product documentation impacts the adoption and ease of use and success of our product.

Planning the Improvement Actions

There is no magic formula to design an improvement plan. The following table provides, for each user survey topic group, some remarks to think about and a basic reference plan of action:

Topic	Remarks	Reference Plan
Awareness and Frequency of Use	Increase the awareness on your documentation project and collaterally the frequency of use, requires involving management roles of different levels, either to enforce the awareness or to act as radiators of information.	Identify your main communication channels. Identify your contact person (Product Owners, Product Managers, Lead Links, CEO, CTO, Scrum Masters) Inform them about the need to increase the documentation awareness Design the layout for your different communication topics, for example: updates, warnings, issues. Be simple and direct. Schedule those communication that can be schedule Start communicating. Be consistent
Search Behaviour and Page Design	Once we know our users' behaviour when reading our documentation, we can support that behaviour and implement some changes to help them take the most of their time using our documentation. Both search behaviour and page design benefits from having a text formatting, page layout and visual elements guidelines. Having templates for each type of page also helps.	Design you style guidelines: text formatting, header/section strategy and naming, use of visual elements. Identify which type of pages are you using: Overview, Getting Started, API Reference Guide, Tutorials, FAQ. A Google search or your preferred conversational LLM (Large Language Models) can help you here! Apply your templates to all your documentation pages. Start with the most used pages. Iterate! Be consistent.
Keeping Our Documentation Up-to-Date	Keeping our documentation up to date is a tough and cross-teams task. Again, involving the management roles of your company is of great help.	Identify the Subject Matter Expert (SME) for each of the topics of your documentation. Agree with them to schedule and set up regular documentation reviews Implement a reminder for you to follow up this task. Create a checklist for the SME to perform their reviews. Keep simple and effective. Check prerequisites, processes or tasks, tools versions and code examples.
General Perception	General perception depends on many topics. Some we can handle (transparency, support, content quality, etc), some we just can't (users not happy with their jobs, users prefer to use a different tool but are not allows, or just bad working habits). Remember to focus in those issues you can fixed.	Keep a fluent and frequent communication with your users Make them feel part of an active and helpful community .

The End?

Documentation projects are, in most cases, living organisms. They are born, they grow, they interact with their environment, and adapt to new surrondings and demands. To keep our documentation alive and quicking (an our users satisfied!) communication is key.

Then iterate!

Improving Your Development Documentation Project (2 of 3)

Javier Hernández — Fri, 03 Mar 2023 11:35:34 +0000

What this article covers

Basic guideline to design a survey to get feedback from your documentation users.

Tools

MS Forms.

Introduction

Now that we know the current status of our documentation better (See Part 1), it is time to talk about our users. Why? Because we have created the documentation for them to be able to use our products, platforms or tools.

But what do we know about our users' needs? Who are they? We may all have assumptions about them. But in fact, we know nothing most of the time.

A user survey is a good method to discover how our users perceive and use our docs, to know their current needs and to decide what to improve first.

Read the following steps to know how to prepare your user survey.

Step 1 - Design a User Survey

To design a user survey we need to know what to ask. But language is tricky so even if we are technical writers, we should double-check the survey's questions with another colleague (and a UX designer, if possible).

About the following questions take them as reference to create your own survey:

In which team/product do you work?
What is your role?
How (un)familiar are you with the Write your documentation name here documentation?
How often do you read the Write your documentation name here documentation?

Never.

From time to time.

A few times a month.

Monthly.

Weekly.

I don't even close that tab.

Which topics do you need to find in the Write your documentation name here?
Which topics would like to find in the Write your documentation name here?
How (un)satisfied are you with the Write your documentation name here documentation?

Very unsatisfied.

Unsatisfied.

Neutral.

Satisfied.

Very satisfied.

Please explain briefly why you are (un)satisfied with the Write your documentation name here documentation.
How (un)useful do you find the Write your documentation name here documentation?

Not useful at all.

Not useful.

Neutral.

Useful.

Very useful.

Explain briefly why you consider the Write your documentation name here documentation (un)useful.
Do you bookmark the Write your documentation name here pages you need?

Never.

I only bookmark the topics I need.

I bookmark Write your documentation name here main topics only.

I bookmark the Write your documentation name here home page only.

Always.

Please let us know to what extent the following statements apply to you personally:

When I need to find some information on a page, I make CTRL+F:

Never.

Rarely.

Sometimes.

Often.

Always.

When I need to find some information on the [Write your documentation name here] pages, I scroll:

Never.

Rarely.

Sometimes.

Often.

Always.

How often do you use the Write your documentation name here page Search box:

Never.

Rarely.

Sometimes.

Often.

Always.

Regarding the content of a page, what do you prefer?

A plain content structure - No tabs, no accordions. All the information is shown at once.

A plain content structure containing some visual elements and disclosing content progressively.

If you were to make one suggestion for improving the Write your documentation name here pages, what would it be?

Better visual design.

Content should be more comprehensible.

Content should be easier to find.

Others (Develop your answer).

Acknowledgement: Thanks to Daniela Diener and Roksana Skryzcka for reviewing the initial survey.

Why These Questions?

Design your questions according to the topic you want feedback about for example: user browsing behavior, page layout preferences, missing topics, etc.

To know which type of feedback we are addressing with the sample survey of this page, read the following table:

Type of Feedback	Question Number	Explanation
Your users (role, team/product)	1, 2	Knowing the role, team or product of our users, helps us to identify: Our audience. Which role/teams are reading our docs the most This information can lead us to develop role or team/product focused documentation, or address specific issues or lack of interest impacting the documentation.
Awareness by role, and team/product	3, 4	If our platform, toolset, product or project has a lot of people using it, checking the awareness level is a must to double check that our people know where to find the documentation they need, and what we have prepared for them.
Frequency of use	3	Answers to this question will tell us if our documentation is being used and how much. Knowing this, we can take further actions to deepen the engagement, or reinforce it if the docs are not being checked frequently.
Topics of interest	4	Too many times we create the docs that we think would be of use for our users. This question will tell us if we are right, and which topics need to be revamped (or removed).
Level of (dis)satisfaction	5, 6	A satisfied user is another word for useful docs (and product!). A low level of satisfaction gives us the chance to ask Why?, and find the source of that dissatisfaction.
Usefulness perception	7, 8	We can think that our documentation is useful but, again, our users will either confirm it or deny it.
Access point to our documentation	9	Sometimes we think that our users access directly our documentation typing the URL in the browser. This question will tell us about the bookmarking habits of our users bookmark. With that in mind, we will have a better idea of the impacts of changing any page or section name that could probably be bookmarked. Here, an effective and reliable communication strategy for changes is key.
Browsing and search behavior	10, 11	Browsing and search behavior have a decisive impact on how we will design our pages, and which visual elements can be used. For example, using collapsible elements may cause troubles to CTRL+F users that, for example, work with Chrome.
Reading behavior	10, 11, 12	Same as previous topic.
Direct Improvements	13, 14	This is the open-air gold mine. Users will tell you what they want and see as a positive impact for the docs.

MS Forms

Use any survey creation tool that fits your needs. I used MS Forms because it was available and provided an easy way to:

Visualize the number of participants.
Provide different kinds of diagrams to visualize the results of the questions.
Download the results in a consumable Excel format.
Easily share the survey.

Step 2 - Schedule the Survey

Scheduling the survey at the right time is as important as the survey itself. We are all focused on providing value to our projects and don't want to get distracted.

So check in advance with the required roles (POs normally), the best date and time to run the survey.

If your users are not your teammates, Customer Support or an equivalent department may be the ones to seek.

When discussing the time for the survey, remember to:

Share the objectives of the survey.
Set the time available to complete the survey.
Explain the importance and benefits of their collaboration.
Ask them to request all team members to attend the meeting.
Try to not interrupt their workflow.

Tip: For agile product development teams, including the survey during the daily or retrospective meeting seems the right time.

Step 3 - Survey Time

During the survey meeting remember to introduce yourself and:

Present the documentation improvement project: What, Why and How.
Explain the importance of improving the docs.
Explain the structure of the survey.
Release the survey!

To Be Continued…

What's Next?

The next article will analyze the results of the survey, and identify the most important ones.

Improving Your Development Documentation Project (1 of 3)

Javier Hernández — Wed, 18 Jan 2023 17:10:20 +0000

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, Hemingway or QuillBot.
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: 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. Not verbose: 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. 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

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.