Improve docs experience for UX Scorecard JTBD: Identify and troubleshoot performance issues of a deployed application by monitoring its environment
As part of the FY20-Q3 documentation OKR &1678 (closed), this issue pertains to a "job to be done" (JTBD) in GitLab--"Identify and troubleshoot performance issues"--which has been evaluated by UX as part of an UX Scorecard Review.
If you are working on this issue, review the linked OKR and the UX Scorecard Recommendations Handbook page for more detail. Then review the links below, per the OKR instructions.
UX Evaluation issue - #11713 (closed)
UX Evaluation video - https://youtu.be/nUdSqrvWeiA
UX recommendations - See "Documentation Opportunities" here #11713 (comment 173444586) and MR here gitlab-foss!32781 (closed)
Product designer - @ameliabauerly
Based on the steps in the OKR epic, use the checkboxes to indicate when each step is complete, and use the format below for notes and plans. You are welcome to alternatively link any/all subsections to an additional issue or a Google doc, to work there instead.
-
Review existing info -
Review SEO -
Document and improve SEO
-
-
Consider potential UI doc link -
Review and improve documentation content -
Test the instructions -
Plan documentation improvements/additions -
Ask questions of and share plans with Product Designer -
Implement doc changes
-
Plans & Notes
1. Review existing info
Overall, after going through each step of the process, my overall grade would be Negative: C.
The individual steps of the process work okay when you know what they are but, the real issue is that there are many steps a user has to complete and if any detail is missed, there isn't much to help them find their way. I had to have someone walk me through the process initally, and then had to enlist their help again when it didn't work as I remembered. Without additional help, I was stuck.
Documentation opportunities
- Current documentation focuses on how to set this up with GDK. It doesn't tell users how to set this up from the UI.
- Current documentation doesn't mention things like Ingress and that you need to add the endpoint into CI/CD settings.
- Current documentation doesn't mention anything about how to set up CI/CD. You would have to find a separate and (currently unlinked) doc on AutoDevops and figure out which pieces of AutoDevops need to be added to see metrics.
Other opportunities
Is it possible to link all of these steps together? Is it possible to make this a more obvious process with just one (a few steps)?
2. Review SEO
The first results from Google point to the Auto DevOps and Prometheus docs. Duckduckgo on the other hand point to the admin monitoring and Auto DevOps docs.
DDG | |
---|---|
a. Document and improve SEO
SEO seems in a good shape.
3. Consider potential UI doc link
4. Review and improve documentation content
a. Test the instructions
As an MVC, let's try to solve the following that Amelia pointed out:
if I'm using k8s and AutoDevOps, which of the documentation options do I use, and which pieces do I need to set up?
With the knowledge I have now:
- I'd go to https://docs.gitlab.com/ee/topics/autodevops/#auto-monitoring
- Be directed to read the requirements https://docs.gitlab.com/ee/topics/autodevops/#requirements, from which I need all.
- First is GitLab Runner. I know you can install it separately in its own server, but if I use k8s inside GitLab, I can install it as a manged app. This is not mentioned.
- Next is the base domain. There's a bunch of docs here, but there's nowhere mentioned that this can be automatically set up by installing the managed app Ingress.
- Next is Kubernetes. We mention its version, although you don't have to worry if you're installing it via GitLab. The load balancer is also mentioned under Kubernetes, which is the same as Ingress (mentioned in base domain).
- Finally, Prometheus. We mention the response metrics, but they feel out of place. They should be in the Prometheus doc. There's nowhere mentioned that you can install it via the managed apps.
- After all that, I go again to https://docs.gitlab.com/ee/topics/autodevops/#auto-monitoring, only to find out that I don't even need to follow the 3 steps outlined there to get the initial metrics that are provided out of the box!