Follow-up from "Initial refactor of Documentation process"

The following discussions from !17593 (merged) should be addressed:

  • @marcia started a discussion: (+3 comments)

    Directly assign the Technical Writer for the relevant [DevOps stage group](https://about.gitlab.com/handbook/product/categories/#devops-stages)
  • @marcia started a discussion: (+4 comments)

    That's way too broad. I'd leave this out, or:

    - Tracking issues and merge requests that contain documentation changes they are assigned to.
  • @marcia started a discussion: (+5 comments)

    - Reviewing all significant new and updated documentation content, whether before merge or after it is merged.
  • @marcia started a discussion: (+2 comments)

    We should add somewhere that the user permissions, as well as product badges (tiers) must be added before merging the original MR and cannot be deployed without it.

    I'd make a whole section for "skipping tech writer's review". I'd add smt like:

    When merging an MR before being reviewed by a tech writer, make sure to check:

    • Broken app anchors, search for app/views when changing a heading
    • Added corresponding badge
    • User permissions for the feature
    • Every new directory starts with an index.md file
    • All new features are described and linked from its higher-level index file
    • Use _ instead of - in file names (e.g., this_is_a_correct_file_name.md
    • Illustration files append the GitLab version (e.g., my_illustration_v12_3.png)
    • Etc... (other things already described through this guide)
  • @marcia started a discussion: (+2 comments)

    Developers, Technical writers, and others may help further refine this plan at any time when requested.
  • @marcia started a discussion: (+3 comments)

    Maybe add here the label set for feature docs? Or link to where we talk about it?

  • @marcia started a discussion: (+3 comments)

    Here we could add all the must-haves of docs changes I mentioned before. (comment added to the line 199) :)

  • @marcia started a discussion: (+1 comment)

    Maybe change to smt like:

    - Technical writer (Optional). If not completed for a merge request prior to merging, must be scheduled

    Or maybe add that it is optional to MRs that need to be merged urgently, as long as we are assigned to an issue afterward, so we can provide "post-merge" review/feedback.

    Also, I'd add that if the code maintainer merges MRs with docs, he must make sure that... (that stuff I added to the comment in line 199)

  • @mikelewis started a discussion: (+1 comment)

    Given our new more continuous release process and our improved processes as a team, I think we should now ask Eng to adhere to have TW 'review before merge,' with 'review after merge' being cast as the exception.

    So we'd reframe this line, and also modify 103 ("- Optionally, the Technical Writer for the DevOps stage group.") to something more like "- The Technical Writer for the DevOps stage group (unless an exception for a post-merge review is granted by the Product Manager and Technical Writer)."

    WDYT? This would require other edits to this section too, so we'd have 'how to decide when to request/grant the exception' rather than just 'how to decide when the review should happen'.

    Happy to take all this to a follow-up MR, given the complexity and further discussion that may be needed.

Edited Oct 24, 2019 by Evan Read
Assignee Loading
Time tracking Loading