These articles about engineering process always put the responsibility solely in the implementing engineer's lap. Always more and more work to achieve JPL-level capability maturity, no matter your budget or headcount. Of course we want unit tests for every case, and verbose explanation in every atomic commit message, and architecture documents that are seldom read before they become stale. But make sure you also get your story points done for this sprint and meet your OKRs for this quarter.
> But make sure you also get your story points done for this sprint and meet your OKRs for this quarter.
The problem here is the points aren't measuring quality, they are measuring a type of velocity that doesn't take into account quality if you aren't getting points for that work.
Read: PMs often drive a timeline that accepts engineering risk, but not responsibility for that decision when it doesn't work.
This is fundamentally missing the point about what story points are, and goes to show you’re unfortunately stuck in another of the many companies using them poorly.
Many (poor) product managers look at velocity dropping and blame the team, or try to pack sprints. In fact, this is the time to open dialogue with the team and get to the bottom of why.
Often, it’s because tech debt or poor architecture is making it difficult to implement even simple features. The team might be burning out. There might be an overwhelming number of bugs and support tickets that need to be addressed.
Story points aren’t a target to hit, or even a KPI. They’re a barometer for team and process health. Unfortunately most engineering and product managers either don’t get it, or are unable to appropriately communicate that fact upwards.
I can only directly relate to solo/small-team projects:
I find writing text (preference: Markdown) and sprinkling it with visualizations (tables, graphviz...) to document stuff very useful and productive.
I don't see this as a burden but rather the opposite. A good portion of programming is not writing code, but thinking and communication. Using text as a direct output of this process helps in many areas. Mostly because we have a limited capability of keeping stuff in our heads at any given time.
A typical categorization of these documents would be:
- specification: describing the thing you build in detail
- todo-lists: organizing actions
- guides/instruction: describing usage of the thing you build in a accessible manner
- meeting & discussion protocols
The thing is: None of these things are extra or can be avoided. The only difference is whether you write them down or not.
The article describes something I would put into the fourth category, or maybe a fifth where you describe intent historically (like design documents).
I personally don't write design-documents or ADRs, nor have I ever seen them. But I assume that these become valuable in larger organizations and teams with a higher communication overhead. As soon you need to talk about these things over and over you want to write these down.
> As soon you need to talk about these things over and over you want to write these down.
This is the relevant part, to me. Can we do this documentation process JIT when someone asks about it? Maybe even convert the dialogue (in chat) or transcript of the conversation into the documentation.
I just started to write anything down basically...
When a collaborator or client talks to me or when I think about something, then I open a markdown file (first often just a notes.md) and just write in bullet points, and gradually organize it into categories.
I put these in version control as well since a while.
Thought experiment: if something is not worth writing down, is it worth discussing?
> Thought experiment: if something is not worth writing down, is it worth discussing?
Writing things down in a way that can be consumed by others is usually significantly more work than discussing that same thing live (whether in text or verbally). As such, I would say that the answer is obviously yes.
Not really because there isn't a JIT budget in most projects, and they usually only get allocated via escalations, some of which imply doing the work for free.
I've been intrigued by ADRs for a bit, and this post prompted me to start a conversation with my current team. Quoting something I posted in my internal slack:
> Note that my goal, with ADRs, is not to increase the amount of time we spend on decisions! If the answers are "I didn't think too deeply and I'm going with my gut" it's still better to have that documented. If we find that we're getting bit by bad decisions, we can look at how those decisions were made and how we can improve them at that point, with much more context.
what you mention are real pain points, though from my experience they actually were a lot simpler than locking info away in some external tool. there is very little additional cognitive cost with adr's and from what I've experienced they add other value too such as a record of why things were done which saves a lot of time when you're ramping up and onboarding new team members who have a tendency to discuss why things are done in a specific way and not another. when used correctly they're not just another thing to take care of but an actual time saver (have personally avoided many meetings by simply pointing new people to them - and they have the benefit of structuring and capturing the architecture discussions in a central place right next to your code ... (if the git log history isn't enough for us we use gitlab comments on changes the same way we would use it on code). it's brilliant because it's so simple imo.
