Hi folks, I was pruning bookmarks and came back on this article. It hit different on a second read though and I wanted to share it here. Here is the original article:
Even though the article is fairly short, here are a few key excerpts I selected:
“Documentation gives everyone an equal playing ground. It puts the knowledge from a privileged few in the hands of everyone, regardless of their standing.”
“If you are building, designing, implementing, maintaining, or consuming anything that someone else will build, design, implement, maintain, or consume, you will need to write documentation!”
“Psychological safety is paramount, and documentation is critical to creating a safe, welcoming, and equitable environment for all contributors to succeed.” — Riona MacNamara, Senior Technical Writer @Google
This is something I stress with my young Jedi. By virtue of having had a horrible memory all my life – or at least, for as long as I can remember – I learned to take notes very early in life. And when I read code that I wrote 40+ years ago, I see comments, slightly whimsical, explicitly addressed to my future self. So, if for no other reason than enlightened self-interest, I ask the padawans’ to doubt their own self-confidence that they will remember everything, and often a few months later, I have the opportunity to say “I told you so.”
It is said that if you want to be a great writer, one needs to practice, as with any instrument. So, the act of documenting not only provides info – either to your future self or others – but also can improve one’s skill at documenting, provided there’s an effort to be diligent and engage beta-readers.
In addition, the need for documentation opens up an opportunity for those who struggle with coding but can string words together into meaningful, clear sentences. It’s an avenue for those who wish to contribute to a project. This includes artists / graphic designers and others beyond those who actually put words to silicon.
This was how I really got my start contributing to open source communities like Fedora. My first contribution to Fedora was a Fedora Magazine article explaining how to install open-source Minecraft server software on Fedora. It was only much later that I picked up more programming-oriented tasks.
This gave me an idea: does anybody think it would be feasible / effective to set up something for the RIT FOSS community for people to link to documentation for their projects, and let people check and provide feedback for each others’ documentation? Perhaps something like this already exists on a larger scale than RIT?
Full disclosure: this is coming from somebody currently overhauling his very messy documentation on a project, who would benefit both from feedback and thinking critically about others’ documentation.
Actually this is a really interesting idea. One of the primary responsibilities I have between January and February is to get a “FOSS@MAGIC runbook” published, most likely similar to how I set up RITlug’s Runbook a while back:
It uses a combination of Python Sphinx for the documentation toolchain and ReadTheDocs.org as the publishing platform. I also have a template GitHub repository that makes it easy to fork a new docs repo and get up and running fast:
No promises, but maybe we can try to encourage some “Doc Days” or something, for folks who want help with documentation but don’t know where to begin. Perhaps I could give a guest lecture next time I am up at RIT for RITlug or another club.
A big +1 for Sphinx as a documentation system. Lovely HTML and PDF results. I don’t use EPUB much, so cannot comment on the quality of the output there.
– I learned to take notes very early in life. And when I read code that I wrote 40+ years ago, I see comments, slightly whimsical, explicitly addressed to my future self. So, if for no other reason than enlightened self-interest, I ask the padawans’ to doubt their own self-confidence that they will remember everything, and often a few months later, I have the opportunity to say “I told you so.”
Perhaps I could give a guest lecture next time I am up at RIT for RITlug or another club.