Skip to content

Latest commit

 

History

History
72 lines (55 loc) · 3.8 KB

documentation-workflow.adoc

File metadata and controls

72 lines (55 loc) · 3.8 KB
Raw

Documentation Process for Product Change

Documentation is required when:

  • A new or enhanced feature is shipped that impacts the user or administrator experience.

  • There are changes to the user interface or API.

  • A process, workflow, or previously documented feature is changed.

  • A feature is deprecated or removed.

1. Design stage

For any user-facing feature or change, the responsible PM/engineer should create a DOC ticket linked to the feature’s design document. The ticket should also specify a subject-matter expert (SME), who will be the primary point of contact for the Docs team to reach out for questions and feedback.

Docs team should designate a writer to assign the ticket to. The writer can offer feedback on the design from a user’s perspective early in the feature design stage, as well as help with writing user-facing strings.

2. Release planning

Once it has been determined which the feature will be included in, PM/engineering should notify Docs team the release date that the feature documentation needs to be ready by.

At this stage, the feature should be relatively developed, and the writer should provide an estimate of efforts required to complete the ticket as well as a due date to complete the feature by.

3. Draft for review

The writer works with the engineer to produce a draft of the feature documentation. This step may include the following:

  • Tag the engineer in the ticket or design doc to ask clarifying questions

    • It is okay to use private messaging to get answers especially if you have many follow-up questions.

  • Schedule an interview with the engineer to conduct a more in-depth investigation of the feature or concepts behind the feature for complex changes

Draft for a new feature should be written in a separate branch of the Git repository. The name of the branch should contain the ID of the ticket itself.

The draft should be finished at least three business days before the due date of the doc ticket. Leave a longer time window for reviews and revisions when the change is complex.

Once the draft is review-ready, open a pull request to merge the branch the draft is written in and invite the SME as well as a peer writer to review. The writer should notify the reviewers that their reviews have been requested as many do not check their GitHub notifications.

For feature documents that are long and span an entire page or several pages, consider making a staging preview so that the reviewers have an easier time reading through your content.

4. SME review

Below are directions for the SME to review a documentation draft:

  1. Read through the document. Particularly, pay attention to the following:

    • Is the document easy to read and skim?

    • Is it missing any important information?

    • Is critical information properly highlighted?

    You are encouraged to offer any feedback you have. As someone who is reading the draft for the first time, your perspective is valuable regardless of whether you think you are good at writing. The writer will also use their judgement to decide whether to incorporate your suggestions.

  2. Answer any questions that the writer asked regarding the document.

  3. If you requested changes, review the edits after they are made. When you think a doc is satisfactory, approve the Pull Request.

5. Peer review

Peer review happens in parallel to SME review. The purpose of peer reviews is to minimize typos and mistakes, as well as ensure the documentation follow a consistent style. As a peer reviewer, read through the document and pay attention to the following:

  • Am I able to follow this document?

  • Are there concepts or terms that are unclear to me that could be better linked?

  • Are there typos or deviations from the style guide?

6. Publish

Once a draft has passed both reviews, it is ready to publish. Merge the PR to publish the final draft.