[organsnyder]

For the past few weeks, I've been digging into a codebase that is legendary among my team for its complexity. While I have disagreements over some architectural choices, the biggest pain point has been the lack of documentation: when I look up the JIRA story referenced in the git commit, it's often a 4-pointer (the highest value we use before we break stories up) with no context. I found one story that had EIGHT pull requests linked to it, and all that was documented was "modify {entity}".

This code base is not even two years old, and I'm already concerned about its long-term viability. The colleagues that worked on it are extremely helpful, but details are fading from their memories over time. Its one saving grace is the fairly extensive test suite, so at least I have some degree of confidence that I won't be breaking things whenever I look at it the wrong way.

[parvenu74]

Perhaps a framework for minimal effective documentation would help. Requiring documentation that starts with "As a {role} I want to {verb}" might not be as effective as saying an application can be defined as a set of features, and each feature is described by it's list of acceptance criteria -- each of which map to one or more unit tests. In addition to all of this would be something in free-form prose from a business operations person describing why a feature needs to be added or modified. "Our competition is kicking our ass because they have feature X in their product and we don't -- we need to fix this." I'm not sure every feature should have something that looks like a mission statement but it would certainly elucidate the motivation for adding/modifying the feature in question.