Merge branch 'docs-with-code' into 'master'

Add documentation for docs-with-code workflow

See merge request gitlab-org/gitlab!25769

doc/development/documentation/workflow.md

@@ -248,6 +248,133 @@ The following details should be included:
 - Include suggested titles of any pages or subsection headings, if applicable.
 - List any documentation that should be cross-linked, if applicable.
 
+### Including docs with code
+
+Currently, the Technical Writing team strongly encourages including documentation in
+the same merge request as the code that it relates to, but this is not strictly mandatory.
+It's still common for documentation to be added in an MR separate from the feature MR.
+
+Engineering teams may elect to adopt a workflow where it is **mandatory** that docs
+are included in the code MR, as part of their [definition of done](../contributing/merge_request_workflow.md#definition-of-done).
+When a team adopts this workflow, that team's engineers must include their docs in the **same**
+MR as their feature code, at all times.
+
+#### Downsides of separate docs MRs
+
+A workflow that has documentation separated into its own MR has many downsides.
+
+If the documentation merges **before** the feature:
+
+- GitLab.com users might try to use the feature before it's released, driving support tickets.
+- If the feature is delayed, the documentation might not be pulled/reverted in time and could be
+  accidentally included in the self-managed package for that release.
+
+If the documentation merges **after** the feature:
+
+- The feature might be included in the self-managed package, but without any documentation
+  if the docs MR misses the cutoff.
+- A feature might show up in the GitLab.com UI before any documentation exists for it.
+  Users surprised by this feature will search for documentation and won't find it, possibly driving
+  support tickets.
+
+Having two separate MRs means:
+
+- Two different people might be responsible for merging one feature, which is not workable
+  with an asynchronous work style. The feature might merge while the technical writer is asleep,
+  creating a potentially lengthy delay between the two merges.
+- If the docs MR is assigned to the same maintainer as responsible for the feature
+  code MR, they will have to review and juggle two MRs instead of dealing with just one.
+
+Documentation quality might be lower, because:
+
+- Having docs in a separate MR will mean far fewer people will see and verify them,
+  increasing the likelihood that issues will be missed.
+- In a "split" workflow, engineers might only create the documentation MR once the
+  feature MR is ready, or almost ready. This gives the technical writer little time
+  to learn about the feature in order to do a good review. It also increases pressure
+  on them to review and merge faster than desired, letting problems slip in due to haste.
+
+#### Benefits of always including docs with code
+
+Including docs with code (and doing it early in the development process) has many benefits:
+
+- There are no timing issues connected to releases:
+  - If a feature slips to the next release, the documentation slips too.
+  - If the feature *just* makes it into a release, the docs *just* make it in too.
+  - If a feature makes it to GitLab.com early, the documentation will be ready for
+    our early adopters.
+- Only a single person will be responsible for merging the feature (the code maintainer).
+- The technical writer will have more time to gain an understanding of the feature
+  and will be better able to verify the content of the docs in the Review App or GDK.
+  They will also be able to offer advice for improving the UI text or offer additional use cases.
+- The documentation will have increased visibility:
+  - Everyone involved in the merge request will see the docs. This could include product
+    managers, multiple engineers with deep domain knowledge, as well as the code reviewers
+    and maintainer. They will be more likely to catch issues with examples, as well
+    as background or concepts that the technical writer may not be aware of.
+  - Increasing visibility of the documentation also has the side effect of improving
+    *other* engineers' documentation. By reviewing each other's MRs, each engineer's
+    own documentation skills will improve.
+- Thinking about the documentation early can help engineers generate better examples,
+  as they will need to think about what examples a user will want, and will need to
+  make sure the code they write implements that example properly.
+
+#### Docs with code as a workflow
+
+In order to have docs included with code as a mandatory workflow, some changes might
+need to happen to a team's current workflow:
+
+- The engineers must strive to include the docs early in the development process,
+  to give ample time for review, not just from the technical writer, but also the
+  code reviewer and maintainer.
+- Reviewers and maintainers must also review the docs during code reviews, to make
+  sure the described processes match the expected use of the feature, and that examples
+  are correct. They do *not* need to worry about style, grammar, and so on.
+- The technical writer must be assigned the MR directly and not only pinged. Thanks
+  to the ability to have [multiple assignees for any MR](../../user/project/merge_requests/getting_started.md#multiple-assignees-starter),
+  this can be done at any time, but must be before the code maintainer review. It's
+  common to have both the docs and code reviews happening at the same time, with the
+  author, reviewer and technical writer discussing the docs together.
+- When the docs are ready, the technical writer will click **Approve** and usually
+  will no longer be involved in the MR. If the feature changes during code review and
+  the docs are updated, the technical writer must be reassigned the MR to verify the
+  update.
+- Maintainers are allowed to merge features with the docs "as-is", even if the technical
+  writer has not given final approval yet. The **docs reviews must not be blockers**. Therefore
+  it's important to get the docs included and assigned to the technical writers early.
+  If the feature is merged before final docs approval, the maintainer must create
+  a [post-merge follow-up issue](#post-merge-reviews), and assign it to both the engineer
+  and technical writer.
+
+Maintainers are allowed to merge features with the docs "as-is" even if the
+technical writer has not given final approval yet but the merge request has
+all other required approvals.
+
+You can visualize the parallel workflow for code and docs reviews as:
+
+```mermaid
+graph TD
+  A("Feature MR Created (Engineer)") --> |Assign| B("Code Review (reviewer)")
+  B --> |"Approve / Reassign"| C("Code Review (maintainer)")
+  C --> |Approve| F("Merge (maintainer)")
+  A --> D("Docs Added (Engineer)")
+  D --> |Assign| E("Docs Review (Tech Writer)")
+  E --> |Approve| F
+```
+
+For complex features split over multiple merge requests:
+
+- If a merge request is implementing components for a future feature, but the components
+  are not accessible to users yet, then no documentation should be included.
+- If a merge request will expose a feature to users in any way, such as an enabled
+  UI element, an API endpoint, or anything similar, then that MR **must** have docs.
+  Note that this may mean multiple docs additions could happen in the buildup to the
+  implementation of a single large feature, for example API docs and feature usage docs.
+- If it's unclear which engineer should add the feature documentation into their
+  MR, the engineering manager should decide during planning, and tie the documentation
+  to the last MR that must be merged before a feature is considered released.
+  This is often, but not always, a frontend MR.
+
 ## For all other documentation
 
 These documentation changes are not associated with the release of a new or updated feature, and are