"Richard Stallman, revered by some as a genius (after all, he won a McArthur “genius” grant in 1990) and by others as a crackpot"
When I first heard him speak many years ago, I thought he was a real crank. My negative thoughts centered around:
1 - How can we build the next Microsoft without true ownership?
2 - Does his model of thinking demand that 100% of the population be technical enough to troubleshoot their computers?
3 - I can see people writing software for love, but who writes all the documentation?
As the years go by, he's one of the few people who sounds less like a crackpot, even though he hasn't softened his extremism. With the current state of patent trolling, it's getting harder to create the next Microsoft. Improvements in GUIs is taking some of the issue away for #2. But I still haven't figured out #3.
> I can see people writing software for love, but who writes all the documentation?
1. People like me? :) I genuinely love writing documentation. Though I should mention it's easier to write books/tutorials than to write detailed documentation of the software you are yourself not writing, which brings me to point 2.
2. Writing documentation is very much a part of software-writing. It's usually best to do write documentation as you're writing the software... I haven't met anyone yet who really hated the process, so I wouldn't consider this to be a big problem at all.
I too write documentation. Not exclusively, but in my day job I often write manuals and other documents for our software, and I've done documentation work as a volunteer for Project GNU.
It's no more strange that someone would enjoy writing documentation that it is that someone would enjoy writing software, though just as non-developers don't understand the joy of programming, I imagine that non-writers don't understand the joy of documenting.
So a question in return... Do you share my belief that documentation tends to lag in most projects? And if so, is the bottleneck not enough documentation writers, or not enough engineering time and attention? I've assumed it's the latter, though it could be the former. Or is it something else?
Do you share my belief that documentation tends to lag in most projects?
Absolutely.
I suspect that the number of people interested in writing software documentation is fairly small: they have to have enough knowledge of software engineering to be able to understand what they are writing about, and they have to be good writers. Anyone could learn software development, but not everyone does. And anyone could learn how to write well, but not everyone does. So the set of people who learn both is even smaller.
On commercial software engineering projects, my experience is that documentation of any sort is made as much of an afterthought as possible, if even that. Unless there's some business case (i.e., obvious money) that comes from spending time on documentation, then it doesn't make it very high on the priority list. Which is unfortunate, because as a software developer, I've wasted a lot of time figuring things out that should have been documented. So money can be saved later on, even if no money is "earned" up front.
For free / open source projects, the story may be different. There's not necessarily paid engineering staff involved, so if documentation doesn't get written, I can only presume that the developers either didn't want to, didn't know they should, or felt incapable of writing it. I find it hard to imagine taking a principled stand against having good documentation.
BUT... in my anecdotal experience, I've encountered volunteer open source software developers who in fact did seem resistant to accepting offers of volunteer help with documentation. So I'm not really sure what's up with that.
It was not meant as an attack at all. It just seems to be a very under-appreciated skill. I've yet to see a firm whose documentation is current more than 6 months after a major release. If you're able to keep up, you're more in the minority than your realize. :-)
#3 is being crowd sourced already for many for profit companies and open source projects via wikis, blogs, forums, videos, podcasts, and Q&A sites populated primarily by volunteers. Particularly with games, documentation is sometimes intentionally not included to allow "explorer" players debate, theorycraft, and publish knowledge about the game for fun, notoriety, and sometimes profit.
We've also seen further pushes to higher level languages, automated testing, improved version control systems, better and more accessible bug and feature tracking products that begin to take the place of official documentation or at least let it be automatically generated.
I also don't think we've reached the end of innovation in this area of self documenting code plus incentivized crowdsourced documentation. Slow incremental changes are eventually going to make that current help link at the top of your software app extinct, or at least look like a dinosaur compared to the elegant evolution that takes its place.
I'm with you on self-documenting code, but what about user documentation, and documentation of APIs?
Now I'm not saying the current model in for-fee software is right. I just wonder, "If it's this hard when you're paying people to do it, how about when you're not?"
I hope to be proven wrong! :-) My company has a great tech write, but I live in fear of the day when someone buys one of his screenplays and he doesn't need us anymore...
Aren't there companies like mashape for documentation of APIs (or at least through their software/proxy)? And if you decide to charge for it, ~20% goes to them. Works for me, but I don't know if that is the cool thing to do…
The thought process came to me many years ago when Microsoft was an example of a startup that built itself from scratch and was very current.
I've come around to broader thinking since then. And Microsoft has changed some too. But it has gotten harder to create companies from scratch due to restrictions on developer freedom. (Patents) There are other reasons that have made it easier, but those are tangential to RMS's topics.
RMS is extreme, but your questions don't seem that hard to to imagine answers to.
1. Why would we want to do that? What problem does creating the next Microsoft solve?
2. I have never heard him claim this. Free software means that you have a right to troubleshoot and resolve problems yourself if you want... not that diy is the only option
3. Why can you see one, but not the other? Some of the best documented software is foss. For example, Its hard to beat Emacs documentation.
It doesn't matter how good the man pages are, I can't give emacs and latex to my mother and expect her to produce a document. In general, FLOSS really sucks at supporting nontechnical, mainstream users.
I understand your point, but I was talking about documentation, not ease of use (sometimes they go hand in hand, sometimes not). Also to further my point about docs in emacs, emacs goes waay beyond just a man page, documentation is baked into everything. Everything is in there... minimal googling required. If you can't tell... im still high on my first few weeks playing with emacs, plz excuse my cool-aid stains.
1 - At the time, creating the next Microsoft meant creating a company from scratch, which built products that the whole world uses. There are many economies of scales that great software companies can achieve.
2 - He didn't claim this explicitly. It was my interpretation of the results of everyone growing their own. I'm less convinced of this today.
When I first heard him speak many years ago, I thought he was a real crank. My negative thoughts centered around:
1 - How can we build the next Microsoft without true ownership?
2 - Does his model of thinking demand that 100% of the population be technical enough to troubleshoot their computers?
3 - I can see people writing software for love, but who writes all the documentation?
As the years go by, he's one of the few people who sounds less like a crackpot, even though he hasn't softened his extremism. With the current state of patent trolling, it's getting harder to create the next Microsoft. Improvements in GUIs is taking some of the issue away for #2. But I still haven't figured out #3.
Edited for formatting