[ale] A use for Windows . . .

[Michael D. Hirsch]

These are all excellent points.  There is both a lack of documentation 
written for Linux and a lack of help tools (e.g. context sensitive help 
systems).  The latter needs serious coding skills, but one would think 
that any of us could help with the former.  The question is how?

Who amongst us would like to give an ALE presentation on how to write 
documentation for Linux?  This can be as broad or as narrowly 
interpreted as you like, though I would like to see it touch on 
tldp.org, HOWTOs, and contributing to GNOME or KDE documentation.

--Michael

On Friday 01 November 2002 01:34 pm, Eric Anderson wrote:
> 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.


---
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.