flexfax: Re: HylaFAX Documentation [was: Re: Mail to fax]

[George Zeigler <genz1968@mtu-net.ru>]

Hello,

Sat, 08 Apr 2000, χΩ ΞΑΠΙΣΑΜΙ:
> George Zeigler <genz1968@mtu-net.ru> wrote:
> > [snip]
> > O come on!  I remember having to read the documentation to get my
> > HylaFax working.  It was really a pain.  Main problem, was that it was not
> > in a manual type format, so that a person could teach himself HylaFax.
> 
> Please explain 'manual type format' - do you mean contents pages, chapter
> structure, page numbering? Or do you mean PDF format rather than html?

	I am referring to how information is presented.  A manual with
different chapters or divisions.  Each chapter having the purpose of
making the reader capable in an area of HylaFax. Simple stuff first, complex
last.

	A chapter talking troubleshooting would have been nice.  Explaining
what certain files are good for:
/var/log/messages
/var/log/mail/"files"
/var/spool/fax/doneq/"files"
/var/spool/fax/config
/var/spool/fax/modem or config.ttyS#
	and how there should only be two config files at most in that
directory.  I ran faxaddmodem and faxsetup a few times with different ports.

 Checking common problems such as getting rid of the
"@" sign in the dialcommand line in /var/spool/fax/etc/config.ttyS#

	I posted to the list that I had problems.  Was told to post
/var/log/messages
	I did that.  
Told to post the 
c0000### file corresponding to my /var/log/messages posting.  I did that.
Told to post my /var/spool/fax/etc/config.ttyS1 file
Told to check my /var/spool/fax/etc/config file for something
Told to take the @ sign off my dial command.
Correct my faxgetty line in /etc/inittab 

	etc.

> >  It
> > was all technical pages and notes etc, which are really useful only for
> > those who know what it means in the first place.
> >
> 
> Hmmm. The theory is that the html documentation should give a broad, yet
> detailed view of all things HylaFAX. The technical stuff is in the man
> pages. The FAQ tries to give another access route to the same information
> at all levels of knowledge plus all the dynamic shortlived info.
	If your lucky enough to find a solution in the FAQ that's fine.  If
not, then you really aren't much more learnt in how to analyze a problem.  The
FAQs don't teach.  They're not supposed to.

> You seem to imply that the html documentation is *too* technical - perhaps
> the answer would be to have a 'Easy Guide'?
	I am referring more to a trouble chapter that gives a checklist of
things too look for.  My problem was relatively easy for instance.  Faxgetty
line in /etc/inittab was not inserted and I had to remove the "@" out of my
dialcommand line.  I read every man page that I was told and FAQ and you name
it.  It was irking to find out that in the end, that my problem was a simple
one, that a nice troubleshooting chapter could easily have knocked out.  Not to
mention, explaining to me what files are useful for analyzing problems and what
files usually have to be tweaked to solve problems.  It was a week I think
before I found out about the c00000## files, and with those babies, you can
nail your problem when posted to the thread.

>  - but my feeling is that if
> you tried to write something like this it would end up as a copy of the
> html documentation anyway.
	I would have liked to have had the material in chapter format with
*examples*, so that I would understand that my level of knowledge of HylaFax was
a step further upon reading each chapter.  I would read the HylaFax material,
and could not really grasp in which area my knowledge of this program had
increased in specifics.  Each section should try to succeed in it's goal of
making the reader capable in a specific area of HylaFax.
 	The man pages were the pits.  Take sendfax for instance.  I decided to
use the sendfax command line.  I was trying to avoid this, as I like GUIs.  So
I read it, shoot out a fax, and it did not work.  I had all sorts of options in
the sendfax line.  I whined to the list and Nicko informed me that my options
were not in the correct sequence.  I was told to read the man page, which I
had.  I went back and found this line: 
"The order of options on the command line is significant." 	
That kind of stuff was just frustrating.  A nice "Let's shoot out a fax!"
section with *examples* would have been nice.  

	Hope some of this complaining is useful.  All in all, I am happy with
HylaFax and am grateful for the help I received on the thread.  I just feel the
documentation is a real weak area for new guys.  That's why I wrote the HOW-TO
for SuSE users, as it was a small way of giving back:-)

Thanks
George