Rosalyn's COMPLETELY LOST in free software blog

Rosalyn's COMPLETELY LOST in free software blog

Hey! I got a blog!

Hi everybody. My name is Rosalyn Hunter, and I've been using a GNU/Linux system exclusively since about 2001, so I've used a lot of software that hadn't reached version 1 yet.

Now a zillion people will tell you to switch to free software, but hardly anyone tells you how many programs there are to choose from, and when you do choose, some of them aren't very good, and some of them work... sort-of.

So if you use free software exclusively, like me, you have to spend time diving into a completely unknown program that may crash your system, or more likely just frustrate the heck out of you. Unless you are lucky, new free software usually comes with a manual that says:

USER MANUAL (write a comprehensive explanation of the program here)...

and so youre stuck!

Sometimes learning to use new free software is like pulling teeth. You know that you've got to do it, but that doesn't stop the fact that it hurts like heck!

Sometimes learning to use new free software is like pulling teeth

In this blog, I am going to explore this pain. This is my COMPLETELY LOST in free software blog. Feel free to post your own experiences too. Maybe we'll come to some kind of catharsis, or we might even learn something?



Robert Romberger's picture

Not all supposedly stable, 1.x+ versions have documentation either. This is definitely a problem throughout the FOSS world. Understandable, yes, since many of the programmers are looking to "scratch an inch" or solve a problem of their own when they write the software; however, they should be thinking twice before plopping said software out to the public to tackle without clearly defining what problem (itch) the software is supposed to solve. I think it would be easier to develop documentation if the community knew what the software was supposed to do before they had to download it and try it out. Developers should also take some time to comment their code in a meaningful way - this function does this, this class does that, etc. - rather than the cryptic "doesn't work yet" which I have seen too often to specify any one piece of software as an offender.

Another thing that some developers would like is to have the community write the manuals for them. Okay, the developer has identified an area that they need help with. The community still needs a rudimentary idea of what the program is supposed to do to be able to find common ground to be able to write a user guide. Again, not high on the to-do list of a developer that says, "works for me".

Which brings me to my last peeve, lack of developer communication. Great, works for you, but doesn't work for me. So, how do I make it work? RTFM? What FM? Answer your e-mail! I've seen many developers create a distribution of their software, then completely abandon it. As far as I am concerned, I'm free to abandon your software and let anyone (and everyone) know what you think of your work and your potential user base. Good luck finding a job, buddy. Software development is a two way street. You have to have some communication with your potential user base to see what problems they are having and see if you can solve those problems either with new code, or a simple "you use it this way" comment. A quick look at SourceForge or Freshmeat will show you that there are plenty of other developers out there looking to scratch that same itch, and many of them are serious about helping the potential user base actually use their program.


Ryan Cartwright's picture

I suppose they imagine documentation to be some kind of magic skill that comes coupled with mind-reading ability. When you come up with something for the first time, it just stands to reason that you, the developer, are the only person qualified to write the basic documentation. Asking someone else to do it is asking them to make guesses --- and that's asking for wrong documentation (of which free software has plenty). In fact, this is usually the real problem with finding free software documentation: not too little documentation, but too much conflicting documentation.

Expecting users to write much of the documentation is a terrible practice but there are some uses the programmer doesn't envisage and this is where user docs, in addition to programmer written docs, come in handy.

As an example a coder may produce a CMS and produce documentation that describes what each function does etc. but this won't help a user who wants to know how they can use the code (without having to write extra modules) to produce the site they want.

Users can often find workarounds - not to bugs in the code but to decisions made by the coder. These workarounds will often enable users to employ functions in ways the coder did not envisage but which are never-the-less valid.

There are different types of documentation and it needs to be written from different perspectives. A user manual is not always the same thing as a user guide or a howto and whereas a coder should document a module writing guide or a API manual, it is likely to be an experienced user who can write the best Howto. As an example a programmer may document every menu option and toolbar button of a word processor but a user-written Howto on mail merging may prove more helpful in the first instance.

Of course there are exceptions to both sides of this but I guess that proves the rule :o)

Terry Hancock's picture

Absolutely. We aren't talking about a specific package here, so we're handwaving a lot. But, I have encountered code for which there is NO documentation. NONE. Sometimes the filenames give you a vague idea of what is going on, and sometimes they don't. Sometimes I can read the code and figure out what's going on (but probably only if the program is written in something like Python, which I use myself and is very compact, and even then, only if it's a pretty simple program).

So, being a pro-active writer-type who might actually write some documentation if I can ever figure out what to write, I look up the programmer and *ask* him some questions.

Sometimes -- maybe even most of the time -- this step is successful, and the programmer talks to me to answer some questions, and something useful comes out of that. Unfortunately, there are also a few times when he basically tells you to buzz off: needless to say, those are the kind of programs that tend not to get documented very well.

The point (well, my point anyway), is that in order for users to start writing HOWTOs and tutorials and other guides, the programmer needs to have written the API guide or the documentation for the menus, etc.

Unfortunately, another common flaw is to say some thing like:

"Open flagrel: Opens the flagrel".

Where "flagrel" is some piece of impenetrable jargon that the programmer uses in his daily life, but we are very unclear on. Even more often, it will say:

"Open object: Opens the object".

This is even worse, because I *know* what "object" means and the programmer *knows* what "object" means -- but we may not mean the same thing!

Author information

Rosalyn Hunter's picture


Rosalyn Hunter has been on the internet since before the web was created. Born into a family of instructors, she has made it her life's goal to teach others about the important things in life, such as how to type kill -9 when a process is dead. She lives in a little house on the prairie in the American West with her husband, her three beautiful children, a cat and a dog.