I think this is really just level 0 of what documentation is from everything I'm seeing. That sounds harsh! But what I mean additionally is that this is laying the necessary and important groundwork to increase the legitimacy of documentation efforts. Being a backbone/level 0 I would caution you to keep in mind
incentives to try and avoid
perverse incentivesRight now there are close to 0 incentives to either create or maintain documentation unless they're inherent in the team already. Or in the case of specific offerings business pressure (Example: API to external developers, but this also requires a business model that means lots of external developers that can't be interfaced with in a higher touch way).
The perverse incentives I can think of immediately which are by no means exhaustive:
1. Increased visibility means increased visibility by management: A double edged sword where management must pick the right metrics to incentivize the production of good documentation. And on the other hand, increased visibility(internally and externally) empowers them to buy into the value produced by documentation efforts and help their teams build documentation habits.
2. This system necessarily increases # of tasks to be completed by a team. Over-subscribing to new task notifications leads to notification blindness or even worse notification dread. I personally love batched tasks that are relevant and important. I do not like things that interrupt focus or even worse interrupt my focus with things that are irrelevant at the current point in time. Nailing this is one of many things to be nailed in order to make the difference between being happy with a tool and feeling overwhelmed.
1 and 2 above can be generalized a bit. With the additional tooling you build on top of your "backbone" you are setting cultural, management, implementation, and usage standards and habits!
So this leaves some core questions to inform the goals of this additional tooling to raise the profile of documentation.
- What metrics should management focus on, how can they use this? Is it about keeping documentation updated as often as possible? Is it about producing documentation that the readers find informative? Is it about reducing errors in the documentation? Is it about X words per month? Is it about knowing which developers are the most likely best writers for a specific area of documentation? Does someone need help improving their documentation abilities?
- Do documentation writers feel empowered rather than overloaded? Do they find value in the documentation that others are writing for them? (I.E. you notice them struggling implementing a feature, maybe there is relevant well written documentation to get them unstuck!)
- And as readers of the documentation... it's not always just internal teams. What tasks are 3rd parties trying to solve with the documentation? Very granular documentation requires a "wide walk" of documentation. Very task focused documentation can mean missing additional information that allows the reader to generalize the task specific documentation to a broader use case. How are readers reading and engaging? I.E. They go to figure out how to do Task A and read section B on page 1, section A,C on page 3, section D on page 4. In this process they notice something slightly incorrect. Rather than just a thumbs down are they empowered to make changes or ask clarifying questions?
Edit: And to keep this from becoming much longer than it already is :) I have one final important question.
What is "bad" documentation and what is "good" documentation?