I’ve been thinking lately about documentation for open-source projects.<\/p>\n
Most of my open-source contributions are code-based, but occasionally I write or contribute to documentation. Yet the email feedback I recieve is pretty much 100% about documentation that I have written as opposed to code I have developed. I get people just saying ‘thanks’, people giving suggestions, people asking permission to republish it elsewhere, people providing translations, its fantastic and much appreciated.<\/p>\n
I had a recent conversation with roger55 on IRC which went something like:<\/p>\n
<roger55> hey dsd, i just got back from linuxtage graz, it seems you have a few fans out here
\n<dsd> roger55: cool! what were they saying?
\n<roger55> dsd: they love the guides you write<\/p><\/blockquote>\nahem.. I write lots of code as well!! ;)<\/p>\n
The documentation\/documentation-user seems to be a much more thriving and active community than the developer\/software-user community, and from my perspective, documentation authors get a lot more feedback and direct communication with the users. Writing documentation for an open-source project is an exciting and valuable contribution you can make. Tag your email address on the end and you’ll really know when people are benefitting from your work.<\/p>\n
The question I am posing: Why are there so few open source documentation writers in comparison to software developers? Using Gentoo as an example, we have just 15-20 core documentation writers, compared to hundreds of developers who deal with software code and maintenance. Not using Gentoo as an example, many open source projects lack comprehensive and up-to-date documentation, and a lot of existing documentation is written by software developers who write it in response to being asked the same questions repeatedly.<\/p>\n
Writing code is a specialist thing. In the UK, you don’t really get taught how to do it until your 14th year of full time education. It’s very technical and you need to be skilled and have a good knowledge of computers to be an effective developer.<\/p>\n
Yet language and literacy is something you are taught throughout education and life, and using software is a daily thing for many people. No offense to the skilled documentation authors out there, but I don’t see it as such a specialist activity. So where is the mass of documentors, and do they know what they are missing out on?<\/p>\n","protected":false},"excerpt":{"rendered":"
I’ve been thinking lately about documentation for open-source projects. Most of my open-source contributions are code-based, but occasionally I write or contribute to documentation. Yet the email feedback I recieve is pretty much 100% about documentation that I have written as opposed to code I have developed. I get people just saying ‘thanks’, people giving […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-42","post","type-post","status-publish","format-standard","hentry","category-gentoo"],"_links":{"self":[{"href":"http:\/\/www.reactivated.net\/weblog\/wp-json\/wp\/v2\/posts\/42","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/www.reactivated.net\/weblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.reactivated.net\/weblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.reactivated.net\/weblog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.reactivated.net\/weblog\/wp-json\/wp\/v2\/comments?post=42"}],"version-history":[{"count":0,"href":"http:\/\/www.reactivated.net\/weblog\/wp-json\/wp\/v2\/posts\/42\/revisions"}],"wp:attachment":[{"href":"http:\/\/www.reactivated.net\/weblog\/wp-json\/wp\/v2\/media?parent=42"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.reactivated.net\/weblog\/wp-json\/wp\/v2\/categories?post=42"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.reactivated.net\/weblog\/wp-json\/wp\/v2\/tags?post=42"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}