On Wed, 17 Sep 2003 21:05:54 +0000 (UTC), steve@watchfield.com wrote:
>Hi,
>
>I am in the process of designing the on-line help system for my Open Spice website; Spice is a programming language that is heavily influenced by Pop-11.
>
>[1] I want to retain the basic division into doc/help/ref/teach directories. However, I am thinking of adding several new directories such as "example" and "how-to".
>
I think a "HOWTO" category is a very good idea. Here is an
extract from a private e-mail I sent last June (of course,
it relates to the Poplog documentation, but makes some
general points):
Given that poplog is not deficient in facilities for writing simple
rule-base systems, a few "get you started" Wizards might be worth
considering, as a supplement to TEACH files.(A new directory
hierarchy in the documentation??)
Another thought: on Linux, a lot of documentation consists of "How
To" files. We don't really have this category in Poplog: we have
simple and complete reference documentation (HELP and REF) and
pedagogical information (TEACH) and some DOC files for more complete
overviews of what is, but it's mostly "this feature works like this,
and lets you do X, Y or Z" rather than, "if you want to do P, Q or R,
this is how to do it". That's not completely true, but if, for
example, you already know about searching and just want to know which
libraries to use, you *don't* want to work through TEACH SEARCHING.
Similarly, if you want to know how to make a look up table, you can
guess "lookup" and HELP LOOKUP will give you a function that you can
use, but it doesn't cross reference you to HELP NEWPROPERTY or HELP
NEWASSOC.
And although NEWPROPERTY *does* cross-reference NEWASSOC, it doesn't
explain the pros and cons, nor does it cross-reference LOOKUP.
This is not a criticism: the original documentation was written for
a different purpose.
It might be nice to have a HOWTO LOOKUP file, which assumes you
already understand what that means and want to know what facilities
in Poplog are worth considering. Just an idle thought.
(Of course, the first file in this new documentation category already
exists: it is HOWTO INSTALL poplog, ...
I think I still agree with my own suggestions - I'm not sure how other
people feel about use of wizards tho'.
Jonathan
p.s. Steve - did you realise your post had overlong lines in it? It's
still considered standard to break lines at 72 characters in news
posts (to allow for nesting of "> > >" in followups).
--
Use jlc at address, not spam.
|