Commit a2ee997a authored by Evan Read's avatar Evan Read

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

Add documentation for docs-with-code workflow

See merge request gitlab-org/gitlab!25769
parents 8568e12b 21e88d35
......@@ -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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment