
Ask HN: How do you successfully maintain your development narrative? - jonathaneunice
Every project has many steps, including preparatory motions, speculative forays, giant leaps forward, misadventures and dead ends, cleanups, rest phases, zig zags, et cetera.<p>I try to keep some degree of &quot;cogent storyline&quot; together about where I&#x27;ve come from, where I&#x27;m heading (at least, in what direction), and what issues I&#x27;m facing, fighting, or defeating along the way. It&#x27;s not quite &quot;Dear Diary,&quot; but I try to record intentions, expectations, plans, current findings, and thoughts about &quot;next steps&quot; to keep me us oriented and aiming toward the target. Writing these things down provides at least a &quot;strawman&quot; that others can critique and extend, leading to a more consistent shared view of where we stand, and what&#x27;s important.<p>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&#x2F;project management artifacts, etc. Like any story, the narrative should evolve as the plot moves along, but I find a lot of interesting&#x2F;useful information churned into transient notes and artifacts. Both the historical and forward story arcs can be lost amidst the ever-present &quot;what&#x27;s happening RIGHT NOW?!&quot; short-term view.<p>&quot;Agile&quot; techniques and version control systems tackled a lot of the problems we used to face in how we evolve code, but they&#x27;re not specifically focused on helping maintain a project narrative. We haven&#x27;t really achieved the project analog of &quot;literate programming.&quot;<p>So I&#x27;m looking for successful techniques. Do you have any particular wins in how you maintain and evolve your project narrative?
======
angersock
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.

------
jonathaneunice
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.

------
jonathaneunice
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.

------
stephengillie
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.

~~~
jonathaneunice
"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.

