Documentation PR’s Welcome - Why Docs Are Not A Beginner Friendly Task

Recently I was reporting a usability issue with a library, mainly related to it’s confusing or absent documentation. A friend of mine saw the exchange and commented (quite accurately) that it went along the lines of:

  • Me: This library should improve it’s documentation
  • Project: PR’s welcome
  • Me: I can’t write the docs because I don’t know how this works without documentation

My friend also commented “[this] is probably the realest interaction I’ve seen in a while.” and “It kinda shakes up the idea that if people want something in OSS they should do it themselves, and that docs are the easiest way to contribute”.

I completely agree with these observations.

Documentation writing is not a task for a drive by contributor, or a beginner. Documentation writing is a skill in and of itself, that requires many things. From my perspective, I believe documentation writing requires:

  • Linguistic ability - to express ideas clearly to a diverse audience of readers.
  • Emotional intelligence - to empathise with their audience and to think “what would help them in these words”?
  • Technical knowledge - the understanding of the problem space to know how to write the correct documentation.

Generally, when someone is a beginner to a project they lack an understanding of the project audience so they aren’t able to empathise with “what could be useful for a reader”. They also tend to lack the depth and breath of technical knowledge to know what to write for the documentation since by definition, they are a newcommer to this project.

A great way to connect with a beginner is to listen to their frustrations and what challenges the encountered with your project. First, connect how that frustration could be either a failing of the user interface and it’s design (even an API is a user interface). Second, only once you have eliminated design limitations, then consider it to be a documentation problem. As the project contributor, you are in a better position to write documentation than a beginner.

Telling someone, especially a beginner, “docs PR’s welcome” is both belitting to the skill that is technical writing, but also generally considered in opensource to mean “I don’t give a shit about your problem, fuck off”.