Hacker News Reader

Comment by hinkley | Hacker News Reader

I was privy to a conversation a couple years ago that got out of control, shortly after our peacekeeper left the team, and I was feeling a little too much in agreement with one of the participants A to step in and shut it down even though he was winding B up something fierce.

The apex of the argument came down to documentation quality, and at first I thought this conversation was over and A won a bunch of points. I forgot about it for almost a year and then it came back into my brain, moved into the upstairs room, and has been trying not to pay rent ever since. And this is what is playing in a loop in my head:

    What if your documentation isn't shit because you are bad at explaining things.
    What if your documentation is shit because you're bad at writing code that can be explained?

I was really excited about this thread until I read your reply. And now all I can think is 'why is their documentation bad?' prejudging it before even looking at it.

View on HN

Another place this pops up is documentation for processes in a business -- this could be a process for onboarding or compliance rituals or (hopefully not) deployment. Perhaps a business group has a process that is taught to new individuals who join the group through shadowing or song or dance, it is part of the folklore and rich and vibrant spoken cultural tradition of the group, but has never been written down. Then someone attempts to document it, and the result is confusing.

What if the process documentation isn't confusing and stupid because the author is bad at explaining things - what if the process documentation is stupid because the process is stupid and needs to be changed.

Another approach to this kind of thing is to reverse the sequence of "do it", "document it" steps and draft a rough version of the documentation up-front as part of an initial design, while it is cheaper to change the process or system, before work is done to implement it and roll it out.

I sat with two teams that had SEI process forced on them, and both of them had their sabres out before the proponent even opened their mouth.

Both groups fell into child-like glee when it was explained to them that SEI level 1 involves writing down your current process as it actually exists. Which meant they got to describe the dumb stuff they'd been putting up with for years, with various degrees of tongue-in-cheek humor, satire, and sarcasm.

- Send boss email

- wait 2 hours for reply

- bug boss about email

- find out IT Guy already left for the day

- Resume process in the morning

Things like that, and a good time was had by all.

In regulated environments there are potential disadvantages to documenting the current adhoc process in all its glorious confusion -- we may be audited to see if how the group operates in practice adheres to the letter of the documented process. If the culture is particularly compliance-oriented, then perhaps we end up "I'm sorry, to comply with our documented process, we can't proceed to step 5 until after the IT guy has returned to work. Since he's still at work today we'd better pause until he clocks off then returns tomorrow".

What you talk about last is referred to as documentation driven development or readme driven development

I think it's great for greenfield work. Forget existing solutions, if you were looking for a solution, write out how you'd ideally like it to work, after it's written, figure out if you can create something that works like that

I like how you turn a phrase, though I fear some manner of contact-tracing is in order now. The next time I see bad documentation, I'll be thinking of your comment, wondering if it wasn't an aborted attempt at explaining the unexplainable.

This reinforces my notion that when there is no documentation, it's because no one has a clue what is going on.

Reply on news.ycombinator.com