Ask HN: How do you successfully maintain your development narrative? | Hacker News Reader

Ask HN: How do you successfully maintain your development narrative?

3 pointsjonathaneunice5 comments

Every 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?

I once had to explain to our executive team why a project had been such a shitshow...it had ended in a two-week crunch to basically unfuck the work that had been to that point, where I cleaned up a mess one of my devs had gotten themselves into (and which, frankly, I had screwed up and let them fall into).

I used the emails, wiki revision history, and commit logs to piece back together what actually had happened. It's a lot different looking at things after the fact, and saying "Oh, I guess we really did take that long to do something...oh, interesting, yeah, we never had direction from the biz folks here, here, and here, and that's where this kinda went off the rails."

As for keeping together a cohesive narrative, as much as I'd love to be able to look at a bound volume of "The Trials and Tribulations of Angersock, Software Engineer", the only inarguable records are the grey hairs, the worry lines, and the eye tics.

Everything else is basically reality-by-consensus, even if you've got the paper trail to claim otherwise.

Just let it go.

One of the real problem areas I haven't solved particularly well: For complex project I might have several cloned repos or branches, each forked off to solve a particular issue, develop a specific feature, or try a particular approach. There doesn't seem to be a very good or integrated way to keep track of the purpose or intention of each branch/repo. It can be very confusion when trying to switch between them. "What was I doing in THIS repo? Where was I? Where was I heading?"

I've tried keeping a file `THISBRANCH` in each with just a one or two line "what's going on here?" description. Better than nothing--but it's not well-integrated into other repo commands/actions, and is a pain when merging back toward a more upstream repo. In general, Mercurial and Git don't seem to do a very good job tracking "intent" metadata about each repo/branch.

A couple of techniques I've found useful:

1. "New and Notable" philosophy. Clear focus on documenting what is new and notable about each update. Putting it in a larger context than just "this branch/this sprint" and making it meaningful to those who may not be deeply embedded in the project. (Learned/adopted from the Eclipse project).

2. Tagged comments. Be disciplined about tagging comments for specific purposes, such as `# TODO:` or `# FIXME:`, so that those working inside code can quickly jot down their thoughts and observations as they have them, while working, yet they can also be consolidated by IDE views or external grep scripts into broader reports about outstanding issues and options.

3. Labeled commit messages. I often include "ATP" in commit messages, meaning "all tests pass." While you might rightfully assume that actual releases or even pushes to upstream repositories pass all tests as a condition of release/push, my projects follow a "commit early, commit often" protocol that sees many intermediate stages committed to local repos. Unless you're committed to regularly and extensively pruning/grooming repo history, even minor commits are going to be pushed upstream eventually. So I try to embed in the messages shorthand notes about testing status. (A variation on this theme is to include urls to CI test runs.)

4. Diffable formats. Encode as many design notes, change logs, and other project narrative information into Markdown, YAML, RST, or other formats that can be easily diffed and tracked by version control systems over time. Microsoft Office, LibreOffice, and Google Docs also have built-in change tracking and collaboration features, making them another evolvable option, albeit with slightly less transparency than pure text formats.

5. Constant vigilance. A disciplined, repeated return to, and updating of, change logs, release notes, design notes, to-do lists, tagged comments, architecture descriptions, and the other documents that form the project narrative.

I'm sorry, but I don't understand the value in keeping such a narrative. Maybe it's inspiring to you, but it just demoralizes me to think "Well I had a month of solid progress...then 3 months of nothing. I'd be done by now if Life hadn't happened to me."

When I look at my self-driving trash can frame, or my fridge monitor, I don't want to remind myself that I haven't had time to work on them since 2012. I just want to start making progress again and having fun.

"The truth will set you free--but first it will make you miserable."

Less cynically and more constructively: If you have projects or components that you weren't able to touch for a long while, then orienting notes seem even more valuable. They can help reset your context and get you back up to speed, working in a productive direction more quickly than if you come back to a project and have to relearn what you were doing and where you were heading.

Reply on news.ycombinator.com