Don’t Be an Open Source Douchebag
I love open source software. It provides both a neat training ground for programmers, a good place to go scratch that itch. On the other side of things, it provides awesome software for people, including some software that would never come out of a big development house.
Still, there are some issues with free software that don’t really show up to the same degree with commercial software. One such thing is documentation. It’s painfully obvious that documentation is written by people who:
- Already know the software in and out.
- Don’t like writing documentation.
- Know nothing about how people learn.
For instance, when I started a side project a few months back, I was looking for a build system. After settling on CMake, I set about trying to make sense of it. There’s the ever-present getting started example, of course. And then there’s the full reference of everything you could possibly want (almost).
But in between those, there’s nothing. Well, nothing except a book, which just goes to show you that there’s something missing — a professional writer could obviously make some money out of explaining things in a reasonable way.
The problem with this is that it doesn’t match how people learn. Getting started is a good step, but a relatively small one. Most of the time will be spent incrementally expanding the knowledge, moving from beginner to expert. Most time will thus be spend in some kind of zone in between the “getting started” and “reference of everything” levels.
Worse than that, some open source programmers have a tendency to view their full reference documentation as an appropriate resource for everyone. “It’s all in there,” right? But pointing a beginner at a 40-page document detailing all the options of some application when all they want is to run it properly isn’t very helpful. I’m sure you know what I’m talking about if you’ve ever used an open source command line tool.
That ends us up with the really dark side of free software culture. The true douchebags out there will not only be extremely smartass in their RTFM comments, they’ll also be incredibly sensitive and defensive about the software they’re working on.
I ran into a problem with cygwin’s SSHD implementation last week. In searching for the solution, I found this mail list answer:
Wrong. That is uninformed speculation and guesswork. Stop spreading misinformation. Cygwin SSHD has had the support for fully logging in as any user since 1.7, as you have already been told and completely ignored. Go and read the manual. The link was in the previous email I sent in this thread. freesshd works exactly as Cygwin *used* to before it got subauth support: when you log in with a key, rather than a password, you just end up as an admin user.
Wow. This kind of answer is wrong on so many levels. First of all, while he makes it seem like the functionality has been there forever, cygwin 1.7 is still not even out of beta. The chance that an end user has it is about 0. So, with the current version (1.5), supposedly cygwin sshd works just like freesshd. This is clearly false, because the original poster reports one working and the other not (which is, by the way, exactly the same results that I had).
So, a user reporting a problem about logging in gets pointed to a long documentation about security settings in a beta version, doesn’t understand a word from that document (no surprise there), and as a result gets told to “stop spreading misinformation”. Truth is, simply installed like any normal user installs applications, one works and the other doesn’t, something made quite clear by an answer from the original poster in a different place in the thread:
> Are you talking about password or public key authentication? > If the latter, Have you tried the LSA authentication package > in Cygwin 1.7?I don't know. I'll try to deciper that. Sounds complicated. In the meantime, friend is using freesshd.
The essence of what he’s saying (which has been completely missed by the cygwin developers) is that the effort required to get cygwin to work like one would reasonably expect of it is much higher than the effort required to just google for something that just works out of the box. The fact that you could potentially make it work is irrelevant, because he’s not getting any help actually making it work.
He might as well just have said, “I don’t care about making it work for you. It works for me.”
Software companies usually compensate for their complete lack of useful technical support with a good (or at least reasonably decent) amount of help documentation. Free software usually has neither.
I encourage any programmer to practice their technical skills on an open source project. But while you do so, take the opportunity to practice your people skills a bit as well, or why not your writing skills? Don’t be an open source douchebag — someone reporting your software’s flaws is not attacking you personally.
Tags: Asshole, Code, Communication, Learning, Open Source, Software
Code | slicedlime | 
Saturday, August 22, 2009 22:28
9 Comments
Other Links to this Post
-
Twitted by mjasay — Sunday, August 23, 2009 @ 4:00
-
Simfoony » Blog Archive » Blog Day 3 — Monday, August 31, 2009 @ 18:30
RSS feed for comments on this post. TrackBack URI
Subscribe
By Matt, Saturday, August 22, 2009 @ 22:56
I actually have a friend that is a technical writer and, when I can rope him into it, I get him to do at least quick user documentation (typically it’s project’s he’s interested in and using as well). There’s a gap in open source software for the graphic/UI design elements and technical writers. There’s also an over-abundance of unexperienced Project Managers. Yet most projects are constantly looking for developers. I’d take a good Project Manager, a good technical writer or a good graphic/UI designer over the best programmer in existence (well, I’m exaggerating a bit there, but you get the idea).
By Wyatt, Sunday, August 23, 2009 @ 0:27
Good calls all around; if we ever meet in a pub, remind me to buy you a pint for this.
CMake is neat, yeah, but damn are their docs bad. Even two years later, apparently. I was playing with it, trying to convert a tiny project from Autobreakage to CMake (don’t know why, really; sdl_svg is completely unmaintained, at this point), and it took hours of frustration, searching, and finding non solutions to the same problems. And I never got it building on multiple machines; the lecture ended.
If anything, I don’t think you emphasise documentation enough, even. It’s part of why I choose to ignore the jeers and frowns that come my way when I reveal that I’m a Gentoo Linux user: We still have some of the most comprehensive Linux system configuration documentation out there and CURRENT.
For some reason, people seem to think they can write docs once and that’s all there is to it. But the reality is code changes; systems change; technology changes. (Then again, are you primarily a Windows user? If so, how much does the Windows app space deal directly with the gremlins of Windows’ ever-expanding ABI-soup?) If you don’t have a dedicated QA/RelEng team, you had best get used to the idea of always going back over your documentation. This is one place the automatic doc generators can really help; they make the trivial-but-numerous changes mostly transparent.
Speaking of _good_ docs, I think I need to bring up Imagemagick. Most everything of theirs is very nicely documented, formatted, and interlinked, and usage examples abound. Granted, any time you start delving into the arcana of it use, you quickly begin to grasp that the name is no joke, but at least the docs are helpful. It’s how documentation of an end-user application should be.
Inkscape also tries something novel by encapsulating the tutorials and all their directions into regular SVG. They’re not half bad, as it goes; being able to follow the directions of the text and move things around right there is pretty neat.
Personally, I wish I had a better grasp of the vocabulary used to efficiently make good technical writing; I’ve done documentation before, and it really sucks if you don’t know what the requirements actually are. It also sucks to see some of the things you’re up against.
But the Cygwin thing…very lame, guys; very lame. Windows people, in general, seem to have funny ideas about release numbers and installing “beta” software, but that doesn’t excuse that sort of treatment.
You know, I’m just sort of glad that people are starting to at least get that a tiny numeric increase is a tiny patch that probably has nothing but important bugfixes. Might make the creeling question about “new maps?” and other such things less annoyingly prevalent. (Yeah. Right.)
Disclaimer: Typos, nonsense, and rambling are the fault of a drunk keyboard. Also exhaustion. D:
By Doug Holton, Sunday, August 23, 2009 @ 0:37
It’s a catch 22 since people won’t write documentation and tutorials for something unless they understand it.
On the flip side, I wrote a lot of documentation for a couple of projects and wished I didn’t because it attracted more people to the project but eventually we realized that development had essentially stalled (virtually all patches were being ignored) and it would be better for people to use other solutions.
By SteveC, Sunday, August 23, 2009 @ 0:48
I would be happy enough if the distros would just refuse to put anything in /usr/bin, /sbin, /usr/sbin or /bin that didn’t have a man page. Seeing as how they make their money off support, that seems unlikely though. I once wrote a script to find everything in /usr/bin that didn’t have a man page, and the list was atrocious. Coming from SunOS in the old days, where good advice to learning the system was “look in /usr/bin, and read the man pages for anything in there you don’t know about,”, redhat’s stuff is a sad state of affairs.
By Karsten Wade, Sunday, August 23, 2009 @ 4:43
Yeah, the man page situation alone is a bit atrocious.
I wouldn’t ascribe evil motives before the more obvious answer. Manual pages are plumbing – dirty, smelly work. There’s a reason it’s not all done yet, and the answer is *not* because distros haven’t demanded it.
The man page generation is the onus of the upstream. Yes, anyone downstream, such as a distro, can contribute a man page, and it does happen when it’s important to someone.
I’ve been involved in man page discussions over the years, such as part of Red Hat Engineering Docs and in the Fedora Documentation Project. It requires a staffing effort. There are, quite frankly, other more important books to write. It’s also not nearly as much fun, and people aren’t drawn to do it.
That doesn’t mean the distros *shouldn’t* try to solve this, and it in fact is a fairly good cross-distro collaborative item. But it’s going to require someone(s) passionate enough to drive the right people across the distros. It could in fact be customer contributors, or a tech writing class at a University, or a set of document writing sprints, or …
By slicedlime, Sunday, August 23, 2009 @ 9:55
Man pages would be a good start, indeed. But man pages usually don’t really fit that “beginners” label… look at the man page for anything reasonably complex like wget without any prior knowledge, and you’ll be quite overwhelmed. And the man page for gcc still scares me
By Aditya, Sunday, August 23, 2009 @ 13:29
Good article. Also in the past I have been reminded that Open source companies “also need to eat”. Which tells me that OSS companies sometimes struggle to find the right balance between their commercial offerings and their community projects, and there is a greater degree of insecurity.