There's a lengthy thread going on the TECHWR-L technical writers' list about using free and open source (FOSS) applications particularly for technical writers. While it seems that the field is shaping up nicely in terms of tools (this is gratifying to know, considering that I intend to set up an entire tech-writing kit on a Linux system), it still has some problems. This, you might say, is a plea from a non-developer user of FOSS to the development community, asking you to consider deliberate or incidental users
of your applications. (An incidental user would be someone who works where FOSS tools are part of the development suite, but isn't a developer him- or herself, and may not have chosen to use those particular tools under different circumstances.)
Installation: This one gets mentioned over and over again in the TECHWR-L thread, and I myself have numerous horror stories of trying to get something-or-other to work. The crux of the problem seems to be that many FOSS developers assume that everyone else's machine is identical to their development and test environment(s), and so omit (and/or at times omit to mention) crucial external pieces required to run their software, such as DLLs, runtime environments, or codecs. Part of the problem here may also be that FOSS writers in general are kind of cliquey, and get so familiar with the insular world, that they don't realise that the vast majority of non-developer or incidental users don't have the required pieces. ("What do you mean you don't have the Pgrtzkl codec?!
Everyone uses Pgrtzkl!")
For the record, I must point out that
LPetrazickis' graciously added a DLL to the
Slashdot Journal Grabber bundle when I asked him. Which brings me to my point: Don't assume that all your users will automatically have the same environment on their system as you have. If your program requires an external DLL, codec, or what-have-you, if you don't want to bundle it with the application download itself, at least
notify your user base and link to a place where the user can get the missing pieces if required. (Case in point where the proprietary world has got it right -- most pages with PDF downloads also provide a link to download Acrobat Reader.)
Similarly, non-developer users like relatively pain-free installs. Of course, we don't always get them (*cough*FrameMaker*cough*), but most of us don't like to compile our own applications, for instance, or go through five installation steps. If you aren't willing to provide an executable of your program, or an installer for it, you probably aren't going to get many users outside of the developer community. This may be your goal, specifically, but it doesn't do much to promote the use of FOSS generally, if every FOSS developer writes strictly for people like themselves, that is, other FOSS developers. Which brings me to my next point...
Documentation and Support: Being a bunch of technical writers, the Techwhirlers are interested in documentation. Several list members
complained that the documentation, for instance, for OpenOffice is terrible (I scanned it and found that it wasn't all that bad, albeit some of the
nomenclature was peculiar). Personally, I've certainly noticed a lack of quality in documentation in FOSS, but then again, I've also noticed it with a lot of other software, too. My experiences with shareware developers are
often the triumph of common sense (and good writing) over the general programmer mentality. The point being that users in general
want
documentation, for that one rare time when they might be tempted to consult the help file instead of contacting the developer for help. Another
complaint that the Techwhirlers had, pursuant to the lack of (good) documentation, was that FOSS developers and/or support people tend to be a
bit belligerent towards people looking for help. It isn't sufficient to tell your users to "RTFM" if the FM doesn't exist, doesn't cover all the features, is so badly written as to be incomprehensible, or is otherwise less than
useful.
A Couple of Points to Ponder: Pursuant to my earlier points, FOSS developers might consider one of the following two things:
When developing your own documentation,
don't do it solely from the
perspective that you're the person who knows the most about the application, and therefore are in the best position to write the manuals. Think like a user. The user
doesn't know as much about your application as you do; when he or she first opens it up, he or she knows next to nothing about it. So if you are indeed writing for end users (as opposed to writing for a programmer user audience, which is another thing), it's important to approach your documentation with a "beginner mind" mentality. In fact, if you
are going to write your own documentation, take a few minutes to learn some basics of
audience analysis. That way, your documentation will actually meet your users' needs instead of just being what you think is necessary and/or important. (Note to developers: Your changelog isn't actually something that most of your users care about. Tell people what your program is, what it does, and why they need it, not how often you've updated it, which
oftentimes just smacks of programmer dicksizing.)
Secondly, if you can't do this for yourself, bite the bullet and find someone who has the time, the tools, and the skills to do it for you. There are lots of technical writers out there who would be interested in working on FOSS projects (*wave* *hint hint* *cough*), if only to get our names out and to build up a track record -- never mind those of us who actually believe in the philosophy behind FOSS -- that you can probably find someone to put together something acceptable for you.
That said, I have a few more things to say about coolness, and position relative to posturing.
Feature Cram and Coolness: Those of you familiar with the
Jargon File have no doubt run into the term "feeping creaturism," and its more linear ancestor, creeping featurism. Far too much software these days -- open source, proprietary, shareware, and that thing you built one night in a fit of pique-cum-inspiration and now hack on when the fancy takes you -- tries to do too many things, and makes the Frankensteinian transition from workhorse to committee animal (that is, an animal built by committee). Then you get programs like, say, CorelDraw, where the interface simply has so much
stuff on it, you're likely to suspect that you could get it to do your dishes, if only you knew the right combination of things to do. Contrast that with something like the old Armadillo, the shareware security application I worked on. It really didn't have much in the way of UI or additional features (so much so that screenshots were pretty unnecessary in the original manual), but it
was a very good tool for the job. In short, a piece of software which does
one thing well, absent million-
dollar marketing and billionaire backing, will probably be more successful and well-liked by its users in the long term. Which brings me to a small comment about aesthetics...
The Naming of Parts: The recursive naming convention was cute. Really. The first couple dozen times, it was even sort of chuckleworthy.
It's just gotten old. And many of you, thinking in typically hyperlinear engineer-fashion, have missed the most crucial element of it: semiotics.
Yes, part of the fun of the recursive naming convention was that the silly recursive initialism actually spelled something that
signified
something. Later generations of highly literalistic programmer types, who wouldn't know a denotation from a signifier if it bit them on the ass, seem to be entirely too enamoured of meaningless initialisms. Case in point, to
pick on Tomble a bit, because he's the only unilingual FOSS user I know (that I know of), his Jabber client is called "ayttm". I think that's absolutely emblematic of a large subset of FOSS nomenclature -- it's a meaningless, difficult to remember initialism that signifies something only to the developer. I still cannot remember the name of my old window manager under RH; it was something like tvwm. Instead of naming your program "All Y'all Type To Me" or "The Very-cool Window Manager" or something (doubtless
that's more creative than the actual name) and abbreviating it to a cryptic string of letters, think of something
creative to call your program. It doesn't have to be particularly wonderful, although evocativeness is nice (think about my previous example of a protection program called "Armadillo"), and failing that, try descriptiveness. Case in point, I suggested that Tomble call his hypothetical custom-built chat client "NaughtyChat," since isn't that what
everyone does with IM anyway? *grin*
Summation Cum Laudanum: This is by no means an exhaustive list of the barriers to entry into FOSS for non-programmer users, but it does cover some of the major ones brought up by the Techwhirlers, and some of my own besides, generously sprinkled with the sort of wanton editorialising you've come to expect from me. I realise that people are going to completely misinterpret the intent of this essay and be all ready to flame me for being a Microsoft
shill or something (ha!). No, I'm a Microsoft
user because I'm a
technical writer. We're a symbiotic lifeform with programmers, and
the majority of software development
still takes place on Windows, and the majority of
paid tech writing gigs are likewise. That's not to say that I
like being a Microsoft user; does anybody? Caveats aside,
I have very little patience with religious zealotry one way or the other, especially in the face of pragmatic considerations like
getting the job done and
getting the bills paid. However, this
is an essay
on how I think serious proponents of FOSS should go about getting themselves and their software used by
more people who fall across a broader cross-section of computer users in general. That's right, I'm trying to find
ways to make FOSS
more appealing to
more people.
Once we've done that, there won't be quite so many responses like this one from Bruce Byfield on TECHWR-L:
Unless I know a tool very well, I do not want to recommend it. It's a personal risk, especially when I haven't been in a position very long, and it's a risk to the project, especially one with tight deadlines and budgets...Now: new project, new company, and I have to choose an authoring tool to create help. My first choice was the industry leader...To be candid, I could have selected [the industry standard] and nobody would have blamed me if it didn't work - just as nobody will congratulate me if the software I choose
does work. However, you can be damn sure I would be in for it if the non-industry-standard tool I selected caused project problems.
Build a track record, and they will come. To build a track record, you need to have a good, solid, attractive product. To have a good, solid attractive product, well...