[ale] A use for Windows . . .

[Eric Anderson]

On Fri, 2002-11-01 at 11:14, attriel wrote:
> Where Free
> Software falls down hard, and what's holding it back, is basically the
> lack of good documentation, as you commented.

I agree that most Free Software does need good documentation. But I
don't think it is entirely a documentation problem. I believe there is a
programming problem to be solved here......
 
> But, for instance, I was trying to fix the clock on a machine here

...clipped...

> I never did find
> the GNOME sysadmin widget thingie to tell me how to change that, or the
> file that told it that ...

...clipped...

> And once I had the sample command, I could
> check the docs for it and knew what it was doing.  I just didn't know what
> it was called ahead of time!  (and /sbin/clock vs /sbin/hwclock seem to be
> entirely different :o)

I think the previous three quote from you indicate where this
programming problem lies.

1) We should eliminate the need for documentation as much as possible.
As you pointed out above. If you had a "GNOME sysadmin widget thingie"
then you would not need documentation. The "widget thingie" (if written
correctly) would have allowed you to setup your time correctly with a
simple interface.

2) Where documentation is still needed despite our best efforts to make
it easy with "GNOME sysadmin widget thingie"'s, context sensitive help
needs to be in place. Two good ideas that I have seen are:
 a) The question mark button that you click, then click anywhere on the
screen to tell you about that aspect of the program.
 b) The "HELP" button on dialog boxes to tell you about that dialog.

The reason why context sensitive help CAN be so helpful is that since it
knows something about what you are doing it can ATTEMPT to provide
useful documentation. I think this is one area that the command line
interface has significant drawbacks to the GUI. The command line doesn't
know that you are looking for the "hwclock" command, but the GUI can
realize that when you click on the clock on the screen it should bring
up the clock GUI. Then once you are in the clock GUI it can provide help
relating to the clock.

Some free software has tried to provide this, but I don't think the
infrastructure is really in place. Documentation is still written as big
manuals instead of cross-referenced, hyperlinked help that can really
pinpoint to the place that you are having problems. I think most of the
"Help" buttons in GNOME on dialog buttons end up pointing to
documentation that doesn't even exist.

So this context senstive problem is a combination of programming and
documentation. We need to documentation, but we need the infrastructure
in place so that to documentation can be easily found by the software.

> And none of the
> hackers want to work on documentation, they wanna hack (or they'd be
> called tech writers, duh :)

If anyone wants to really hack instead of write documentation, and work
to making the system easy to use. They could start by trying to put the
necessary Help infrastructure in place. A better help browser with some
indexing for searches would be a good start.

-- 
Eric Anderson

---
This message has been sent through the ALE general discussion list.
See http://www.ale.org/mailing-lists.shtml for more info. Problems should be 
sent to listmaster at ale dot org.