2. Doc requests process for feature PMs
-
Feature PMs are responsible for ensuring that documentation is published within the appropriate timelines and locations to meet Teams developer needs.
This means that a PM must start planning for documentation at the very start — along with the rest of feature planning. Writers must start working with the feature PM as early as possible - ideally before R0.
NOTE
After the design specs are ready and finalized, the same can be shared with the writers.
-
PMs choose the appropriate status by engaging documentation needed/not needed on the feature Docs tab. The Documentation for developers? field is on the Details tab of the Azure Boards Feature item. PMs should engage that field as soon as possible – but definitely before the feature enters R0.
NOTE
✔ PMs must indicate whether documentation is Needed or Not needed. That field cannot be empty.
- The Needed indicator gives us (the documentation team) the required heads up to include a Requirement work item in our backlogs – that’s why we want PMs to fill out these fields before the feature reaches R0. When we create a documentation work item, we’ll connect it to the feature work item so all progress is easy to follow.
✔ PM must also plan for a feature walkthrough. We could combine a couple of features and have a recorded walkthrough session.
✔ PMs must select
Needed(for developers) anytime there’s a new capability or a change to an existing capability. -
The PM must provide the TargetDate (R0) and Ring4TargetDate (R4) and meticulously keep both up to date.
-
The Ring4TargetDate tells us when the documentation should go live, and helps us sequence the many documentation tasks that we have. Documentation release is synced to the feature release — the R4 date lets us know when to PUBLISH!
-
We align documentation to the feature Ring4TargetDate but plans can change. You should make a general announcement to update inaccurate Ring4TargetDates during each Shiproom.
-
Sometimes, dev preview (R3.6) documentation is needed prior to the full feature release. The PM is required to let us know if dev preview documentation is required. We’ll add a “Dev Preview” note to the articles until the feature reached R4 and goes live.
If the Documentation for developers? field is blank, i.e., not engaged, or the R0 and/or R4 dates are missing, the associated PM owner will show up on a Shiproom query report. The PM will be asked to update the Documentation for developers? field for the feature. The documentation will be marked as Blocked: Yes for a feature that has a blank Documentation for developers? field.
The PM is the expert on the developer impact of a feature and understands the technical implementation as well as usage scenarios. We rely on the PM to give us the technical info/feature walkthrough we need to create and publish content for a feature — including the end-user experience — so that we can assess what content needs to be changed or added.
✔ We provide a template in the Requirement's Discussion field that outlines the type of information that is needed to accurately document a feature. There are templates for both Teams and Graph documentation.
✔ We welcome any draft documentation that you can provide and will be happy to walk you through the steps for creating a PR in the appropriate GitHub repo.
✔ Please provide links to all relevant PM, API, and Engineering specs.