Home » Post » Rosalyn Hunter's posts

Before reading further... Are you looking for great Linux hosting from a company that cares about GNU/Linux? Pick Dreamhost hosting, get a 10% bonus to the disk space (and support Free Software Magazine in the meantime!)

Rosalyn's COMPLETELY LOST in free software blog

FSM Columnist: Trusted

Write a full post in response to this!


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?

Write a full post in response to this!

Similar articles

0

Do you like this post?
Vote for it!

Copyright information

This entry is (C) Copyright by its author, 2004-2008. Unless a different license is specified in the entry's body, the following license applies: "Verbatim copying and distribution of this entire article is permitted in any medium without royalty provided this notice is preserved and appropriate attribution information (author, original site, original URL) is included".

Biography

Rosalyn Hunter: 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.

Robert Romberger's picture

Developer responsibility

Submitted by Robert Romberger on Sat, 2006-06-17 18:21.

Vote!
0

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.

--
Bob

Terry Hancock's picture

'writing the manuals for them' ...

Submitted by Terry Hancock on Mon, 2006-06-19 20:36.

Vote!
0
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".

Yeah, that's one of my worst peeves too! I hate it when I ask for documentation (or an explanation), and get the standard -- "well there isn't any, why don't you write some" response: How am I supposed to do that if I can't figure out what it does!?

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.

Maybe I'm biased because writing comes fairly natural to me, but I usually write the documentation and the code at the same time. This is so easy to do nowadays: we have a variety of self-documentation systems that make it trivial to turn code comments (and "docstrings" in Python) into readable API and overview documentation that is automatically kept up to date.

Of course, we realize that this kind of automated documentation will never be up to the same standards as real tutorials (which I'll happily contribute to writing), but there's an absolute minimum level of documentation that the developer is the best suited person to write.

I think developers also sometimes miss important understandings of their own work when they don't do this. Figuring out how to express what your goal in plain language is an important step in making sure you know what you're trying to do. Otherwise, there is far too much temptation to write sprawling, confusing, and ill-focused code.

Ryan Cartwright's picture

There are some things a programmer can't document

Submitted by Ryan Cartwright on Tue, 2006-06-20 11:37.

Vote!
0

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

There are some things a programmer can't document

Submitted by Terry Hancock on Wed, 2006-06-21 05:35.

Vote!
0

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!



Other sites

Odiogo