Documentation Training - Sabine Carpenter
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 - Sabine Carpenter -
Add yourself and your trainer as the assignees. -
Commit to this by adding "Documentation" as a knowledge area for yourself. -
Set milestones, if applicable, and a due date to help motivate yourself!
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 as 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 - #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.
- 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 guideliens, 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
- stage
- group
- Support Team Contributions
- customer (if related to ticket)
- Assign to the relevant Technical Writer (TW).
- Find the "Technical Writer" counterpart on the product categories page.
- If it's not a product stage/group (such as GDK), use the technical writing assignments page.
- Make sure to check off:
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: here
- 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. -
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, throw it in #docs Slack asking anyone in #docs to review and merge ASAP, or if it can wait until the assigned TW will be online, ping them in #docs with a link to the MR. Since this will be reviewed by a TW, this does not require a post merge 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
-
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.
- While not required, it is highly recommend to install the docs linters in your local editor to prevent pipelines from failing.
-
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 ZenDesk for tags:document_this
or view documentation support contribution MRs. -
Read over how the Document this function in ZenDesk works. -
Alternatively, you can create issues with the documentation template manually. - Make at least 2 docs MRs as a result of customer tickets:
-
Docs MR that adds content: gitlab-com/www-gitlab-com!70976 (merged) (usually troubleshooting section): (ZD: 185282) -
Docs MR that fixes inaccuracy: gitlab-org/gitlab!50037 (merged) (ZD: 183756 (internal))
-
- Optional: Next level documentation MR "administration". In addition to what was previously covered:
-
Add the appropriate scoped docs label -
Add a milestone (choose current milestone unless less than 3 days away, use 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!
-
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. -
Once complete, add this module to the list of training you have completed!