Create a complete guide for monitoring

Problem to solve

GitLab Docs is the main resource that helps our users learn and set up GitLab's monitoring tools. Documentation is an extremely important part of our product which can make or break the user experience. Having good documentation will reduce the learning curve and the barrier to entry for new users (those setting up monitoring for the first time).

Currently, GitLab Monitoring documentation is very difficult to navigate. The information we're providing is often fragmented and incomplete. Some of the most obvious issues are:

  • Many of the navigation links don't match the pages they lead to.
  • Main nav and breadcrumbs don't match.
  • The documentation doesn't follow an intuitive hierarchy.
  • Documentation is incomplete.

We've been documenting and analyzing the current architecture of the Monitoring Docs in this Mural Board. Your comments on the Mural are much appreciated. The red stickies are the points of confusion and where the docs are lacking something.

Current Monitoring Docs Structure in Mural
Screenshot_2020-03-04_at_14.40.57

Further details

This effort is part of the greater effort to improve the process for enabling monitoring in GitLab. Improving the docs will help us support the user along their user journey.

Epic: Enabling observability features in GitLab

User journeys for enabling Monitoring

Next Steps / Proposal

We all have our own mental models for how we think about Monitoring and hence how the Monitoring docs should be organized. Here's my mental model. You may have a different one. And our users may think about Monitoring documentation in yet another different way.

We need to understand what are the mental models that our users have when they think about Monitoring. What is the information architecture they already have in their heads? Where would they expect to find all the information? Where do they start their search?

  • Document the current IA (information architecture) for Monitoring GitLab Docs
  • Perform a tree test on the current IA to see where our users struggle, where they click, etc.
  • Propose an alternative docs structure based on the results. How can we make the Monitoring docs AMAZING to use?
  • Test the new docs structure using a tree test
  • Create a complete guide for monitoring following the new structure: edit the pages, fill in the missing information, etc.

These steps needs to be broken down into issue, and this issue should probably be promoted to an epic after the initial discussion around this issue is completed.

Permissions and Security

Links / references

/cc @axil

Edited by Nadia Sotnikova