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".