Skip to content

Template and process improvements for documentation

Mike Lewis requested to merge template-improvements-for-documentation into master

What does this MR do?

Updates issue and MR templates to make it easier to contribute documentation and follow the documentation guidelines. There are additional edits to those guidelines (files in /doc/development/documentation) which are following up from https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23951/.

Key changes from the above MR and this one:

  • PMs to provide documentation needs in each feature issue to make it easier for developers to write the docs we need, in partnership technical writers and others.
  • Technical writers will track and review those plans, and be available throughout the process for help.
  • Devs/maintainers can choose to save the technical writer (TW) review for after the merge. They'll merge docs with their code by the freeze for feature changes, regardless of whether the TW review was already performed or is scheduled for post-freeze (pre-release).

To make the above easy to follow, this MR does the following:

  • Adds a Doc Review issue template, mainly for maintainers in each case where they merge code+docs without a Technical Writer review. This can be used not only for the monthly feature release process, but any docs MRs that arise where TW does not review before merge.
  • Adds a Documentation section to the Feature Proposal issue template, for the doc requirements. Anyone can suggest its content and PMs must confirm/complete it by kickoff.
  • Improves the Documentation-only issue and MR templates.
  • Updates the Danger reply on MRs with documentation to advise on the latest processes.

TL;DR:

The following items are new or clarified here.

  • For developers:

    • Authoring docs that are ready to merge with the code by the freeze is required in order for the feature to be merged.
    • A technical writer review prior to that merge is no longer required, though often preferable, whenever time permits.
    • If that review won't happen before the merge, create an issue with the new Doc Review template and assign it to the tech writer. It will happen post-merge/freeze, but before the release.
    • You will now have doc requirements in the issue that were confirmed by the PM and tracked by the stage's technical writer, who can help clarify the requirements or help with any other questions you may have.

  • For those performing a code review:

    • You should also review the docs.

  • For maintainers:

    • You should only merge a feature with its docs, but the technical writer review is no longer required prior to merging (though often preferable, whenever time permits).
    • If the review has not occurred prior to merging, create an issue for it using the new Doc Review template.

  • For technical writers

    • Monitor feature issues for the upcoming and current milestone, ensuring they have good documentation requirements. This includes attending or watching the Kickoff.
    • Monitor and handle Doc Review issues between the freeze and the release.

  • For product mangers:

    • Provide documentation needs in each feature issue by the kickoff to make it easier for developers to write the docs we need.
    • This is now called for in the feature proposal template, so others may draft it.
    • The technical writer for your stage will monitor and review all issues and doc requirements.

Key Review App pages:

Beyond this MR, I have updated the default issue templates in GitLab CE and EE:

  1. Better URL and the words "via this MR":
- [ ] [Documentation created/updated](https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html) via this MR
  1. Added a line:
- [ ] Documentation reviewed by technical writer *or* follow-up review issue [created](https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issuable_template=Doc%20Review)

What are the relevant issue numbers?

https://gitlab.com/gitlab-org/gitlab-ce/issues/55595

Does this MR meet the acceptance criteria?

  • Technical writing team reviews/awareness
  • Product team reviews/awareness
  • Engineering manager and maintainer reviews/awareness
Edited by Mike Lewis

Merge request reports