“No software spec survives first contact with the compiler.”
One of the interesting bits in the project type #1: Team=Both, Code=Up>Down, Docs=Down>Up scenario is when developers write up their feature plans in the upstream repo. Often, these show up in the /doc subdirectory.
- Often, before coding, a developer writes up a description of the new feature they plan to code. They use this document to discuss and negotiate its implementation with other team members.
- When the developer starts coding, code reviews replace the document as the forum of discussion.
- Reading these feature plans and related discussions is like seeing an artist’s preliminary sketches: They represent the intention more than the result.
- Sometimes, these preliminary docs reflect the developer’s concerns more than users’ and customers’ needs. They focus on back-end issues, celebrate accomplishments, and explain decisions.
- These topics tend to focus more on the feature than the user story.
- Toward the end of the project, as the feature approaches release, the developer might add user instructions to these documents.
- Sometimes these plans describe features that didn’t make it into the software, made it in as beta or tech-preview features, or describe features that have been superseded.
In a future post, I’ll write about how to analyze and use these upstream docs to create better customer-facing docs.
Rolfe Dlugy-Hegwer 