A new afterstepdoc approach?

Andrew Sullivan (asullivan@sprint.ca)
Wed, 9 Dec 1998 02:19:29 -0500 (EST)

Ok, all, I have a suggestion for a new organization for the afterstepdoc
files.  This will require a lot of work, and a fair amount of learning on
my part, but I'm willing to do the bulk of that work if I can get a kind
of protocol agreement among the developers and users.

The suggestions I've encountered include the following: the documentation
is too difficult to use (this is a beginner's complaint), is too hard to
assemble (this is partially a difficulty of the Web), has too little
discursive quality (this is a complaint about no ready-to-hand HOWTO), is
not available quickly enough, or is too silly to bother with (a
developers' complaint).  Additionally, there are complaints that
individual items do not recieve enough attention (this is particularly a
problem from module developers who spend too much time dealing with
module-FAQs), and that old problems receive too much emphasis in any
current FAQ.

So, here's my proposal.  It should be regarded as a contrib for 1.7:

afterstepdoc ---> root doc.html page
                    |   | 
                    |   |
                    |   --> sub-FAQs.html (e.g. Pager-mini-FAQ)
                    -->What if I know what I'm doing?

I can think of extra stuff to fit in here.  Under "What if I know ..." are
instructions for finding the man pages, "easy-access" common probs for
developers, and a txt version of the TODO list.

It seems to me that some sort of intro is needed as an auto-start when
someone attempts to install.  I'm not being too demanding here: a simple
text deal will work.  But I think that, if ease-of-use is a desired goal
(I'm not saying it is: I actually think a "high bar" install is a good
thing), a design like what I'm suggesting might be useful.

I have some ideas about how to implement the approach, but I want to see
if this sort of unified doc hierarchy is worth pursuing.  Also, any
additional "tree" item suggestions are (of course) welcome.

Please let me know what you think.


Andrew Sullivan | asullivan@sprint.ca (better)| ajsulliv@mcmaster.ca (worse)
                                   *  *  *
                Go to http://lowrent.org/asfaq/, or issue
'finger -l ajsulliv@mcmail.cis.mcmaster.ca' to find the AfterStep FAQ file.

   WWW:   http://www.afterstep.org/
   FTP:   ftp://ftp.afterstep.org/
   MAIL:  http://www.caldera.com/linuxcenter/forums/afterstep.html