Clarify and Update Documentation Processes for Technical Writing, Engineers, and Product
The Technical Writing team needs to clarify our documentation processes and draft updates to them, get buy-in from affected teams, confirm what we can start doing right away (with minimal cross-team buy-in) to clarify our backlog statuses/priorities (and start doing so), and document and communicate new processes.
-
Create an updated workflow and responsibilities (including issue/MR/label usage) for doc work for each type of potential doc change. This may be more easily reflected as a single list, with caveats based on type of change. Change types involving docs are:
- New product (rare to have a whole new product line, so not our focus now)
- New feature (need to differentiate community vs. GitLab?)
- this is common and we should prioritize (and consider major vs minor feature?)
- Updated feature (need to differentiate community vs. GitLab?)
- this is common and we should prioritize (and consider major vs. minor update?)
- New doc or subsection not tied to a product change
- this is common but does not involve the release process so can we revisit this later?
- Doc enhancement
- this is common but does not involve the release process so can we revisit this later?
- Doc bugfix
- this is common but does not involve the release process so can we revisit this later?
-
The steps for each of the above will be a plan/vision which can then be translated into tangible changes to our process docs and templates.
-
As for responsibilities, high-level ideas are
- For new and updated products and features:
- Product managers include a publication-ready summary of new features and use cases
- Product managers include subtasks under Documentation task, including: Doc requirements (the doc or section needing creation or updates), what doc changes should occur (at a high level, like 'instructions to do X in the UI', table of the parameters for Y, etc.), and other affected docs that will need updates - even as minor as adding links to a new main doc. We could require this is split into 'MVD required for release' vs. 'further documentation needs'
- By certain date, engineer has to either certify that all doc requirements are met or create and link a new issue for further doc changes and assign it to themselves (with a choice in priority level?)
- Document deadlines around doc submissions and reviews, but have Tech Writers check in with each engineer who has an impending deadline (via issue) on a certain date?
- Community contributors are met with the line "If you are writing documentation" here; can we be more specific in what we request for various types of changes? Should there be doc-related questions in the MR? Whose responsibility is it to ask clarifying questions of the contributing developer in order to ensure contributor can offer MVD or enough info for us to edit/write more? A technical writer?
- For new and updated products and features:
-
Update use of labels for all above documentation cases
- End goal is to be able to see priority-sorted view of everything Technical Writing team is working on
- Interim label/milestone/board usage enhancements that we can implement (before getting buy-in from other teams on new processes) in order to clarify all doc priorities
-
Update Issue and MR templates to clarify the doc cases/requirements/responsibilities.
-
Update Technical Writing handbook docs to reflect the above.
Note: This is a starting point for further discussion. I have not reflected all detailed ideas from Technical Writing Weekly 2018-05-30 but we can refer back to those notes and further enhance/discuss this issue.