Documentation Training - Kylie Norquist
module-name: "Documentation"
area: "Product Knowledge"
gitlab-group: "Create:Editor"
maintainers:
- cynthia
- greg
Overview
Goal: You feel proficient at making a documentation merge request.
Length: hours (maybe? please update with a better estimate)
Objectives: At the end of this module, you should be able to:
- Open a merge request specifically for documentation.
- Follow the documentation process.
- Find who the Technical Writer counterpart for the relevant group the merge request is related to.
Stage 0: Create Your Module
-
Create an issue using this template by making the Issue Title: Documentation Training - <your name>
. -
Add yourself as the assignee. -
Set milestones, if applicable, and a due date to help motivate yourself! -
Update support-team.yaml
to indicate that you've started learning this knowledge area:knowledge_areas: - name: Documentation level: 1
Consider using the Time Tracking functionality so that the estimated length for the module can be refined.
Stage 1: Introduction
-
Watch this introduction to docs video (Slides) to get a quick overview. Please keep in mind this was made for external contributors. -
Read about the Docs-first methodology and why our documentation is the single source of truth. -
Familiarize yourself with the Ticket deflection through documentation Support workflow.
Where to ask for help
If at any time, you have questions or need help getting a MR started or completed, please reach out.
- #docs
-
#git-help
- specifically for
git
command line issues
- specifically for
-
#support_team-chat
- You can ping those listed as knowledgeable in "Documentation" or one of the Docs counterparts.
Stage 2: Your first docs MR!
There is a lot of information surrounding documentation and how to do it, but the best way to learn is to start with a small MR and get right into it.
-
Find a super small fix to do. This might be a typo, format issue, small wording change. For this first MR, try not to pick a technical change. - If you can't find anything, you can also consider a documentation issue that's good for new contributors.
-
Make the change via whatever editor you want (local, WebIDE, Web Editor). - Tip: While viewing the page on the docs site, scroll to the bottom and click on "Edit this page" to view the repo file.
- When looking at the repository, if you want to know which webpage it is, search for the title of the page on
docs.gitlab.com
. Note: The navigation is not 1:1 with the folder structure, so you cannot rely on that to find the page. - Branch name should start with
docs-
(or one of other options listed in the branch name scheme). - Make sure the commit message follows our commit message guidelines, in particular:
- 3 or more words.
- Start with a capital letter.
- No period at the end.
-
When you open the merge request, as per our docs MR guidelines, make sure to choose "Documentation" as the template. -
Fill in the template as best you can, the minimum: - Description on change.
- Link to ticket/issue if relevant.
- Add appropriate labels. Minimum:
- documentation (should be automatically added via the "Documentation" template, but check to make sure). Note: This label is also used to track your contributions to documentation, so make sure to add it!
- group scoped label (if in doubt, it should be listed at the top of the docs page)
- customer (if related to a ticket)
- Note: stage, section, Support Team Contributions, and docs-only labels should be added by the bot if you don't add them.
- backporting labels if the change needs to be included in stable releases
- Follow the MR guidelines and set the relevant Technical Writer (TW) as a Reviewer.
- The documentation template will also have instructions on how to find this, but basically refer to the metadata information at the top of the source version of the docs page (this will tell you which stage/group you want to refer to if you're unsure).
- Make sure that the following options are checked:
Delete source branch when merge request is accepted.
-
Squash commits when merge request is accepted.
"Apply suggestion" is used frequently in docs MRs so this is preferred.
-
Submit! - Your first docs MR: !37050
- Once it's been reviewed by the assigned TW, you'll have finished your first docs MR. Congratulations!
Stage 3: Guidelines
Let's now take the time to read up on some of the relevant guidelines in a bit more detail:
-
Go over the Documentation workshop slides from Contribute 2020. -
All documentation guidelines are under the Contributor > Documentation section. You don't need to read everything, but take a browse through to know what's there. -
Read through the documentation process. - Note: Support is expected to verify the technical accuracy of a docs MR before assigning to a TW. When in any doubt, get a technical review from an engineer first.
-
Read the post merge review guidelines. - When would you use this in Support: Got an urgent docs MR? At times, we may want a docs fix as soon as possible.
- If it's in the "Troubleshooting section" of any page, follow the guidelines except assign to a support manager who is online who will do a quick review and merge.
- If it's not, then depending on how quickly you need it, share it in the #docs Slack channel asking anyone there to review and merge ASAP. This does not require a post-merge review, as it involves a TW review.
-
Read about docs deploy. The key thing is to note how often docs are deployed. -
Optionally, read the rest of the site architecture information to learn how the docs site is built.
-
Style and linters
-
Complete the GitLab Technical Writing Fundamentals course on LevelUp (~2.5 hours duration). Collect your badge! -
Read the documentation style guide. - No one expects you to memorize all the style guidelines! Read through it once and try to remember what's covered so that you can reference it later.
-
Briefly read over the topic types page with a more careful read of the troubleshooting section. -
While not required, it is highly recommended to install the docs linters in your local editor to prevent pipelines from failing, or use the GDK. Plugins can be also used from the command line. -
Set up markdownlint. -
Set up Vale. -
Set up a vertical ruler to help you split long lines.
-
Stage 4: From tickets to documentation
Whenever a customer says the docs are confusing or unclear, we should be making a merge request to resolve their concern. If you're not sure what to put in the MR, then you can instead create a documentation issue
-
Review 5 tickets where documentation was created as a result of the ticket. You can search in merged documentation support contribution MRs. Note that not all MRs with the Support Team Contributions in GitLab.org / GitLab label originate from Zendesk tickets, so if you don't see a link to a ticket, you may want to review a different MR. -
__ -
__ -
__ -
__ -
__
-
-
Read over how the Document this function in ZenDesk works. - You can search in ZenDesk for
tags:doc_issue_created
to locate such tickets.
- You can search in ZenDesk for
-
Alternatively, you can create issues with the documentation template manually. - Make at least 2 docs MRs. Ideally, they are part of working on a customer ticket. If so, remember to include a link to the ZD ticket in the MR description. If you cannot find a ticket with an open docs update, you can create any update that meets one of these criteria:
-
Docs MR that adds content (usually troubleshooting section): LINK -
Docs MR that fixes inaccuracy: LINK
-
-
Optional: In addition to what was previously covered, add the appropriate scoped docs label and a milestone to your MRs. Choose the current milestone unless it is less than 5 days away. Otherwise, use the next milestone.
Penultimate Stage: Review
You feel that you can now do all of the objectives:
- open a merge request specifically for documentation.
- follow the documentation process.
- find who the Technical Writer counterpart for the relevant group the merge request is related to.
Any updates or improvements needed? If there are any dead links, out of date or inaccurate content, missing content whether in this module or in other documentation, list it below as tasks for yourself! Once ready, have a maintainer or manager review.
-
Update ...
Final Stage: Completion
-
Have your trainer and manager review this issue. -
Manager: schedule a call (or integrate into 1:1) to review how the module went once you have reviewed this issue. -
Consider watching Contributing to GitLab documentation -
Consider also taking the Code Contributions training which focuses on GitLab code changes. -
Update support-team.yaml
to indicate that you're ready to work on tickets in this knowledge area:knowledge_areas: - name: Documentation level: 2