Finding Answers in Unfamiliar Territory (Documentations are Underrated)

April 14, 2020

Just like many (probably most) people, even after being a developer for close to 9 years now, there are so many things I don’t know. When I pair with other developers on story cards, there are many, many occasions where we both wouldn’t know exactly how to do something, and we have to figure out how to do it.

A few months ago, in my 1:1 with a developer I’d recently (at the time) paired with, she mentioned that she found it interesting that I deliberately go to documentations a lot more than others she’s worked with before. That conversation made me realize that I had noticed the same thing - that many people I pair with often do a search, look at the first StackOverflow post or the first article, and if that doesn’t solve it, repeat with the next one down the search results list. Not only have I noticed it, I had had micro-frustrations with that approach, that I had never tried to articulate before.

This is common enough in the industry that we have memes like this:

Reflecting a little, I realize I usually make mental judgment to categorize a question or problem into one of these buckets, and I treat them differently:

1. a question that everyone using the tool would (at least very likely) have
2. a question that is pretty common, but not quite to the extent of #1
3. a question that’s probably unique to me

A question that everyone using the tool would (at least very likely) have #

When I’m new to the tool or the language and not exactly doing groundbreakingly innovative work, most of my questions actually fall into this bucket. When they do, I would go to the documentation.

Why?

First, because that’s what they are for - they should have answers to very common questions. However, fairly often, they are not straightforward answers, like in the style of StackOverflow. I would have to navigate through it a little, try to find the relevant section, skim or read through it, and check if they have the answers to my questions.

That leads me to the second reason. I like that documentations don’t provide me straight answers. They both force and help me form better mental models of the tool or language I’m dealing with, in a way that something that answers my question straight does not.

It may feel a bit slow for people not used to it, because you may have to navigate the documentation for a few minutes before finding those relevant sections, but I’ve generally found the investment to be worth it. The mental model that I build while I navigate and skim or read through the documentation sticks with me longer, and like lego blocks, are easier to build upon as compared to direct answers to the question I had at hand. These lego blocks speed me up in the medium to long term.

I won’t go so far as to say RTFM, but I do think documentations are somewhat underrated.

In the ideal world I would not even need to do this, because I would’ve had time to read through the documentation before trying or using the tool / language.. but that doesn’t happen all that often, right?

A question that is pretty common, but not quite to the extent of #1 #

This is where I would try StackOverflow, GitHub issues list, or blogs.

They have their uses, but some of my micro-frustrations come from how relying almost exclusively on this approach feels like shooting in the dark without even attempting to illuminate the room a little. (And that illumination lingers, it doesn’t just disappear, so it helps you make better shots next time too.)

A question that’s probably unique to me #

As much as I’d like to think of myself as a unique snowflake, most of my problems aren’t that unique. When my first judgment tells me a problem falls here, I usually try to question that judgment a little, maybe vary one or two parameters of the problem, and find out that it in fact is pretty common after all, or that someone else has faced it.

When it is unique though - that’s when I would post a new question somewhere - on our chat room, StackOverflow, GitHub issues, etc.

Another tool: look at the code #

Another tool that I use from time to time, regardless of the category (although probably more for the latter ones), is to just look at the code. If it’s a library whose sources I can download in the IDE with a single click, great! I would navigate around it and try to make sense of it.

If it’s something else, I may go to the repository, look for an entry point, and try to understand what’s going on there.