KR: Help our TWs and Developers create best-in-class documentation through "Train the Trainer" => 4/5, 80%

FY22-Q1 UX Department OKR

Objective: Make our UX department a "best place to work for designers, researchers, and technical writers."

KR2: Help our TWs and Developers create best-in-class documentation through "Train the Trainer"

Problem

Our current Documentation Guidelines don't provide enough specific information about how to actually write solid technical documentation: crafting sentence and paragraphs, avoiding wordiness, being consistent. While TWs edit the topics that developers and PMs write, timelines and resources don't always allow a thorough edit. Improving the draft documentation from developers will provide better source material.

Solution

Google provides excellent documentation training for developers that we can incorporate into our own training.

As we adapt our documentation process to industry best practices, we will provide training for anyone who wishes to write high quality GitLab documentation. GitLab technical writers will vet the training course by completing the pre-work and the GitLab-specific training class. They will be able to support community and developer writers with consistent standards that are reviewed in the training.

To complete this KR, all Technical Writers will complete the two training sections by April 30, marking yourself as complete in the table below.

  • Susan, Craig, Suzanne: Design the complete training with Google pre-work, GitLab exercises, and GitLab-specific topics, such as Concepts, Tasks, Reference, and Troubleshooting topics.
  • Christie: Review for final polish.
  • February 28: All Technical Writers have completed the pre-class material portion of the Google developer doc training class.
  • April 30: All Technical Writers have completed the GitLab-specific in-person portion of the training.
  • April 30: Handbook includes a Technical Writing Fundamentals page with recorded trainings.

Status

Once you’ve completed the training sections, please mark yourself as complete by checking the boxes next to your name. Don’t forget to add any comments/questions you had about the training to this issue.

Google Pre-Work

Pre-class material link for Technical Writing One

  • Amy
  • Axil
  • Craig
  • Evan
  • Marcel
  • Marcia
  • Marcin
  • Mike
  • Nick
  • Russell
  • Susan
  • Suzanne
GitLab Train the Trainer
  • Amy
  • Axil
  • Craig
  • Evan
  • Marcel
  • Marcia
  • Marcin
  • Mike
  • Nick
  • Russell
  • Susan
  • Suzanne
Edited by Susan Tacker