debian-mirror-gitlab/doc/development/documentation/feature-change-workflow.md

description
How to add docs for new or enhanced GitLab features.

Documentation process at GitLab

At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process.

• Developers: Author/update documentation in the same MR as their code, and merge it by the feature freeze for the assigned milestone. Request technical writer assistance if needed.
• Product Managers (PMs): In the issue for all new and enhanced features, confirm the documentation requirements, plus the mentioned feature description and use cases, which can be reused in docs. They can bring in a technical writer for discussion or help, and can be called upon themselves as a doc reviewer.
• Technical Writers: Review doc requirements in issues, track issues and MRs that contain docs changes, help with any questions throughout the authoring/editing process, and review all new and updated docs content after it's merged (unless a pre-merge review request is made).

Beyond this process, any member of the GitLab community can also author documentation improvements that are not associated with a new or changed feature. See the Documentation improvement workflow.

When documentation is required

Documentation must be delivered whenever:

• A new or enhanced feature is shipped that impacts the user/admin experience
• There are changes to the UI or API
• A process, workflow, or previously documented feature is changed
• A feature is deprecated or removed

Documentation is not required when a feature is changed on the backend only and does not directly affect the way that any user or administrator would interact with GitLab. For example, a UI restyling that offers no difference in functionality may require documentation updates if screenshots are now needed, or need to be updated.

NOTE: Note: When revamping documentation, if unrelated to the feature change, this should be submitted in its own MR (using the documentation improvement workflow) so that we can ensure the more time-sensitive doc updates are merged with code by the freeze.

Documenting a new or changed feature

To follow a consistent workflow every month, documentation changes involve the Product Managers, the developer who shipped the feature, and the Technical Writing team. Each role is described below.

1. Product Manager's role

The Product Manager (PM) should confirm or add the following items in the issue:

• New or updated feature name, overview/description, and use cases, all required per the Documentation structure and template.
• The documentation requirements for the developer working on the docs.
  • What new page, new subsection of an existing page, or other update to an existing page/subsection is needed.
  • Just one page/section/update or multiple (perhaps there's an end user and admin change needing docs, or we need to update a previously recommended workflow, or we want to link the new feature from various places; consider and mention all ways documentation should be affected.
  • Suggested title of any page or subsection, if applicable.
• Label the issue with Documentation and docs:P1 in addition to the Deliverable label and correct milestone.

Anyone is welcome to draft the items above in the issue, but a product manager must review and update them whenever the issue is assigned a specific milestone.

2. Developer's role

As a developer, you must ship the documentation with the code of the feature that you are creating or updating. The documentation is an essential part of the product.

• New and edited docs should be included in the MR introducing the code, and planned in the issue that proposed the feature. However, if the new or changed doc requires extensive collaboration or conversation, a separate, linked issue can be used for the planning process.
• Use the Documentation guidelines, as well as other resources linked from there, including the Structure and template page, Style Guide, and Markdown Guide.
• If you need any help to choose the correct place for a doc, discuss a documentation idea or outline, or request any other help, ping the Technical Writer for the relevant DevOps stage in your issue or MR, or write within #docs on the GitLab Slack.
• The docs must be merged with the code by the feature freeze date, otherwise
• the feature cannot be included with the release.

Prior to merge, documentation changes commited by the developer must be reviewed by:

• the person reviewing the code and merging the MR.
• optionally: others involved in the work (such as other devs, the PM, or a technical writer), if requested.

After merging, documentation changing are reviewed by:

• a technical writer (for clarity, structure, grammar, etc).
• optionally: by the PM (for accuracy and to ensure it's consistent with the vision for how the product will be used). Any party can raise the item to the PM for review at any point: the dev, the technical writer, or the PM, who can request/plan a review at the outset.

3. Technical Writer's role

Planning

• Once an issue contains a Documentation label and an upcoming milestone, a technical writer reviews the listed documentation requirements, which should have already been reviewed by the PM. (These are non-blocking reviews; developers should not wait to work on docs.)
• Monitor the documentation needs of issues assigned to the current and next milestone, and participate in any needed discussion on docs planning with the dev, PM, and others.

Review

• Techncial writers provide non-blocking reviews of all documentation changes, typically after the change is merged. However, if the docs are ready in the MR while we are awaiting other work in order to merge, the technical writer's review can commence early.
• The technical writer will confirm that the doc is clear, grammatically correct, and discoverable, while avoiding redundancy, bad file locations, typos, broken links, etc. The technical writer will review the documentation for the following, which the developer and code reviewer should have already made a good-faith effort to ensure:
  • Clarity.
  • Relevance (make sure the content is appropriate given the impact of the feature).
  • Location (make sure the doc is in the correct dir and has the correct name).
  • Syntax, typos, and broken links.
  • Improvements to the content.
  • Accordance to the Documentation Style Guide and structure/template.