Docs experiment in topic types: Packages & Registries pilot
Summary
Recent user research has shown that users visit GitLab docs to find instructions, reference information, troubleshooting info, and other resources.
Reason | Percentage |
---|---|
Looking for instructions | 35% |
Visiting a page I use as a reference | 24% |
Looking for admin resources | 13% |
Troubleshooting | 8% |
Total | 80% |
(The remaining 20% included browsing new feature info (11%), "other" (5%), and deciding whether to acquire GitLab (4%)).
While 74% of survey respondents were able to find what they were looking for, many commented that it wasn't easy, and ~21% said they did NOT find what they were looking for. (5% couldn't remember.)
Standard topic types help with information architecture design, organizing consistent navigation, and providing a SSoT. These topics can be organized in any number of ways and can be referenced from other topics.
We believe changing our topic design to conform to industry documentation standards (the boring solution) can help users find what they need.
Problem to solve
The design of Help topic content in docs.gitlab.com does not follow industry standards.
Why?
Developers write the first draft of topics based on very basic guidelines within a documentation template. We do not offer them the support required to follow a standard information type, nor are we encouraging a task-oriented perspective.
User quotes
- "This page is just horrible. The pieces of information are completely random and I couldnt have found anything I needed... if the pages would have been organized better, I wouldnt have to spend hours with searching"
- "I'd like a walk through on getting gitlab runner working with docker, ssh, and the other runner integrations"
- "Please make some tutorial repositories on Docker deployment for learning"
- "A few times I found it hard to understand what really need to be done to achieve expected goal"
Proposal
- Run a pilot that reworks a small section of the GitLab documentation into concepts, procedures (tasks or how-to), reference, and troubleshooting "chunks."
- Focus on The Packages & Registries section of the documentation, because it is fairly self-contained and is a good candidate for reorganization.
- In this issue, track the evaluation of topics and sub-topics, and then rework the content to ensure a concept, procedure, reference, and troubleshooting topic design.
- Assess the effort required to rework this content.
- Assess whether the rework resolves user pain points by showing before and after readability scores.
- Consider a usability test comparing before and after findability.
- Next step: Decide whether to iteratively restructure other parts of the documentation following this approach.
Industry standards
Two tenets of software product documentation are:
- An emphasis on a task-oriented user perspective (35% of respondents were "looking for instructions")
- Using basic topic types: Concepts for overview information, Procedures for tasks, Reference material for things like API usage, and Troubleshooting for resolving issues
These topic types are the industry-standard building blocks of user-friendly and task-oriented software documentation. For users to get the most out of their GitLab deployment, they need to understand what features are and how to use them.
Industry standards, such as the Darwin Information Typing Architecture (OASIS Darwin Information Typing Architecture (DITA)), recognize the importance of discrete topic types.
DITA is not a great option for GitLab, since developers write the first draft of our documentation in markdown in a fast-moving, open-source environment. DITA has heavy technical requirements that would prevent community contributions and is strictly enforced. The DITA standard does, however, recognize the importance of discrete topic types and stresses their importance in providing a singular goal for a "chunk" of content.
Results
Updated Nov 10, 2020.
On average, this work brought the reading levels down by nearly 1 point. To do this, I removed extra language and created repeatable patterns.
These topics were already fairly well-structured and so more work was done to edit language than to restructure and update topic types.
While the scores do not indicate an exact reading level, a lower score indicates better readability.
Topic | URL | Before reading score | After reading score | Difference |
---|---|---|---|---|
Composer | user/packages/composer_repository/ | 12.32 | 10.48 | 1.84 |
Conan | user/packages/conan_repository/ | 11.67 | 9.84 | 1.83 |
Container Registry | user/packages/container_registry/ | 11.58 | 10.4 | 1.18 |
Dependency Proxy | user/packages/dependency_proxy/ | 9.71 | 9.99 | -0.28 |
Go Proxy | user/packages/go_proxy/ | 10.37 | 10.3 | 0.07 |
Maven | user/packages/maven_repository/ | 11.44 | 10.07 | 1.37 |
NPM | user/packages/npm_registry/ | 10.86 | 9.52 | 1.34 |
NuGet | user/packages/nuget_repository/ | 11.58 | 11.47 | 0.11 |
PyPI | user/packages/pypi_repository/ | 11.71 | 10.83 | 0.88 |
Average | 11.25 | 10.32 | 0.93 |
Other links/references
Third-party documentation that delineates clearly between types of information: