In this blog post I will reflect on my readings from Teching Open Source chapters 8 and 9.
Chapter 8
This chapter discussed the importance of documentation in code. When looking back at code you wrote weeks or months ago, the more descriptive your comments are the better you or others can understand your work. This documentation can come in multiple forms, such as ad hoc comments while you are working on code or more refined documentation that is user facing.
The waterfall method is useful to those new to technical writing.
- Planning
- Content
- Writing
- Internationalisation/Localisation
- Review If you are ever stuck and think writing documentation is a daunting task, start at the top of the waterfall and take it from there.
Documentation can also be used as a first step to getting involved in a project. It helps you understand the larger project as a whole (like Zulip in my case). Usually developers resist writing documentation because the tools are painful to use or writng is not a main skill. To combat these obstacles we can employ a couple of methods. One is to treat writng as a brain dump of ideas and worry about the quality of writing later. Enabling non-developers to add significant contributions to documentation saves developers from the actual work of writing. Collaboration is also key in FOSS documentation
We can also categorize documentation such as documenting a technical community proceeding like a conference.
Chapter 9
As the closing chapter of this online textbook, the authors reflect on the phrase unanimous with FOSS ‘Release early and often.’ This applies to the textbook as well which aimed to encourage students to particpate meaningfully in FOSS and empower professors to bridge the gap between FOSS and students.