a rant. Bullet points are not skimmable
A code-focused environment that considers documentation as a nonessential task proliferates so many teams and is made evident by documentation that is inconsistent, unmaintained, undiscoverable, restricted and incomplete for ensuring that products are continued and projects are estimable for technology- and version-agnostic software development lifecycles, current and future.
The loss:
- difficulty accessing the documentation itself due to fragmented locations and unmaintained access levels
- difficulty understanding what is legacy and what is current
- loss of time training new team members by having to repeat “what’s in people’s brains”
- apathetic culture to “maintenance” and “docs” due to having been born or onboarded without this mandate to formalize this essential habit
- suffer team-wide cone of uncertainty in estimation from task level of effort, to project planning
As a team we want to develop a system for documentation that:
- is easy to find and made easer to find across the platforms that serve it (Nearby)
- is up-to-date and is kept up-to-date (Current)
- is skimmable for existing team members and is exemplary for new team members (Cumulative)
- is easy to contribute to (Participatory) and is mandatory for contribution (Precursory)
- is comprehensive for foreseeable task estimation (Comprehensive)
- is consistent and follows conventions of nomenclature for directories, resources, scopes, environments, stages, et cetera (Consistent)