Ask HN: How do you successfully maintain your development narrative?
https://news.ycombinator.com/item?id=10048706Every project has many steps, including preparatory motions, speculative forays, giant leaps forward, misadventures and dead ends, cleanups, rest phases, zig zags, et cetera.
I try to keep some degree of "cogent storyline" together about where I've come from, where I'm heading (at least, in what direction), and what issues I'm facing, fighting, or defeating along the way. It's not quite "Dear Diary," but I try to record intentions, expectations, plans, current findings, and thoughts about "next steps" to keep me us oriented and aiming toward the target. Writing these things down provides at least a "strawman" that others can critique and extend, leading to a more consistent shared view of where we stand, and what's important.
But this narrative gets naturally spread across disparate places--code comments, commit messages, documentation, to-do and patch lists, various design notes, status reports and change logs, agile/project management artifacts, etc. Like any story, the narrative should evolve as the plot moves along, but I find a lot of interesting/useful information churned into transient notes and artifacts. Both the historical and forward story arcs can be lost amidst the ever-present "what's happening RIGHT NOW?!" short-term view.
"Agile" techniques and version control systems tackled a lot of the problems we used to face in how we evolve code, but they're not specifically focused on helping maintain a project narrative. We haven't really achieved the project analog of "literate programming."
So I'm looking for successful techniques. Do you have any particular wins in how you maintain and evolve your project narrative?