Documentation Training - Adam Mulvany
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 and your trainer as the assignees. -
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 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.
- 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
- stage (if in doubt, stage/group are listed at the top of the docs page)
- group
- Support Team Contributions
- customer (if related to ticket)
- 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 technical writing assignments page.
- 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: gitlab-org/charts/gitlab!2320 (merged)
- 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 GitLab Learn (~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 structure 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 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 (usually troubleshooting section): Documentation updates to gcp module credentials -
Docs MR that fixes inaccuracy: Making Ansible paths consistent - Not so much an inaccuracy, but it was inconsistent.
-
-
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 3 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!
-
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. -
Submit a MR to update modules
andknowledge_areas
in the Support Team yaml file with this training module's topic. You will now be listed as an expert in this topic on Skills by Person page. -
Consider also taking the Code Contributions training which focuses on GitLab code changes.