I have a love-hate relationship with documentation.
On the one hand, I believe that documentation is a key part in the success of a lot of projects. If you document something, you are removing unknowns from the project, whether it be the rationale behind code changes, or explaining in detail a particular business scenario. However, documentation only works if the documentation is good, and if the documentation is actually read.
Writing good documentation is hard. Technical writing is a skill, just like any other skill, and it’s often overlooked or understimated. A good technical writer in your team is worth their weight in gold, I think.
I recently saw a tweet linking to a post on Medium on the phrase RTFM (or at least the attitudes around it) and how we should retire and rethink it. In the context of reading and writing documentation, I think I agree, although I find that on reading it, I felt pretty conflicted.
I agree that we should have empathy for those asking for help, and
looking for some way throught the incidental complexity of working
with (and in) software. Those who know we know that I’m glad to be of
help in any way, and I don’t shy from answering questions asked of
me. I remember an anecdote way back, when a coworker asked me about
some bits about the git(1) command line: bits of information that could
be gleaned from reading the git(1) manpage, but which I quickly
volunteered. Only afterwards did I realize in good humor that I acted
as a quicker manpage lookup for him; no worries though.
However, the bit I feel conflicted about though is when people ask me questions where the answer I feel is apparent— I readily admit that this may be a failing of empathy on my part; I have been known not to suffer fools gladly, but sometimes I ask myself whether I should cut people more slack.
A few years ago, I worked on a backend service for a client, where we defined the API that their mobile applications would talk to. We were moving from an older system, and so we were working from a blank slate here; I decided to work on documenting and specifying the API first and foremost, before ever writing a single line of code. I spent a couple of weeks on the document, laboriously ensuring that I described and specified behavior and expected parameters of particular calls. I treated the document similar to an IETF RFC, specifying what was strictly required, what was encouraged, etcetera. I even wrote out how the API was to be versioned, and how clients should handle version differences.
I was, and am, pretty proud of that document. I know though that it wasn’t complete and final, and there were things I probably didn’t know to specify in that document. I also thought I kept the language as clear yet precise as I could.
So, imagine how I felt when one of the mobile developers, from an entirely different team, working as part of a different company, emailed me a question about a particular behavior that I knew I specified precisely in the documentation. I felt really annoyed: did this person read the documentation I just sent? I feel like my reply came across pretty coldly, citing chapter-and-verse in that document. RTFM, I almost screamed in my email, although I didn’t– I did bite my tongue.
In hindsight though, I think I should have been considerate. I mean, I did drop an almost-30-page PDF on their laps, and it might have felt daunting to go through it all just to get shit done. Who wants to wade through all of that, if asking a question via email might get the answer much more quickly?
That’s where I think I felt most conflicted about, reading that Medium post. How do you reconcile empathy with the gut reaction of feeling like your time was entirely wasted?
On the one hand, I do admit that maybe my language was too dry and academic and formal in that document, and maybe I could have written a much shorter document describing how to use the API. Maybe I wasn’t actually as clear and precise as I thought.
In any case, a part of me still feels conflicted about documentation, especially after that Medium post. I’m one of the rare folks, I feel, that doesn’t mind writing documentation and even likes to do so, and that I feel sometimes conflicted when my work and effort feels like it’s all for naught, and that no one reads or appreciates what I write. Or gives me feedback anyway, for that matter.
Previously: Books