Re: Task Topics

[Two Ducks <twoducks@globalserve.net>]

Pardon the lateness of mailing. I have been away for the holidays
and only recently returned and am catching up now. Note that the
following is a brief note and that more details will be filled
in.

---------------------------------------------------------------------

OK. After much waffling I have some further discussion on formats and
other help information.

Currently sdoc has not been developped to the point where it can be
used fully for the help documents. SDOC is, however, based on
HTML so for now the documents may be written in HTML and there will
be minimal changes later. Most changes will not be difficult to
add. There are some details at the bottom of this message for
formatting the help for specific purposes and other details on
how the help should be written.

Greg Bell wrote:
<snip>
> Execellant idea, I don't know about anyone else but my little
> installation/file
> maintenance program is at the general point where a help file (although I
> don't think it is needed, but then who can say) can be constructed.  Just
> waiting on some word about file formats/locations/etc.

There are two "locations" I can think of...

One is where to put complete documents. I will set up a cvs directory
for documents.

One is where in the help directory structure (and thus in the cvs
directory structure as well) a file belongs. The location of the help
files in the help directory structure depends upon what type of
help file and what it discusses. Any suggestions? I will write a bit on
my thoughts below...

<snip topic listing>

> Your listing of topics seems more like a on-line tutorial then a help system
> (is there a difference????) but it is a good starting point.
> 
>     Greg

Ya. The help files I was describing are a lot like a tutorial. I will
describe this more below too:...

Obviously more though needs to go into all aspects of the help
documentation. The following will be done shortly and the rest
will be hammered out over time:

1. Help directory structure basics determined.
2. Process for adding help files to structure decided.
3. cvs directory added to contain help files.

I will write again tomorow with some details of these topics.
If there are any problems or topics which must be decided now,
please write so that they may be discussed and completed.

***********************************************************************

Help Docs
=========

Help doc types:
--------------
There are two main help document types which will be added by SEUL:
1. Task help and
2. Application help.

Task help are brief, procedural descriptions on how to perform various
tasks. These are much like HOWTOs but smaller in scope. eg:
  * Copying a file
  * Printing a document
  * Playing a midi file

Application help are help documents specific to applications and
utilities.
These document contain all help for the application.

Applications may contribute both application help and task help.

Task help format:
----------------

Task help documents should have the following parts:
  * Title
  * Short description of task
  * Ordered list of steps

Task help may contain links to other tasks.

Application help format:
-----------------------

I dunno. Haven't thought of this much. Any suggestions?

Help file naming and packaging:
------------------------------
OK. Here it is.

Task help and other (application +) help have some naming and packaging
similarities. The special task help naming is described later.

Help documents may end in either .html or .seul. Right now seul is
the same as html for help so either works. Later when the seul
help doc format is developped seul documents will be different.
This will be handled when the time comes.

The name of the document should be a brief description of the contents
so that they make sence, using underscore as a space character.
For example:

  Copying_a_file.seul
  Installing_a_cdrom_drive.html

The help documents may be stored in a .tar.gz file. If this is done the
first document to be loaded from the file should have the same name as
the .tar.gz file. For example:

  In the file Installing_a_cdrom.seul.tar.gz the first document to
  be loadded by the viewer is called Installing_a_cdrom.seul

It is probably a good idea to name all of the files the same name,
with a number after each of the additional pages. For example:

  Installing_a_cdrom.seul.tar.gz can contain
  Installing_a_cdrom.seul
  Installing_a_cdrom1.seul
  Installing_a_cdrom2.seul

Links between the documents are done as per normal html.

Packaging is important because it allows the user to see only the
one document listed, even if it has 20 parts.

Task Document Naming Convention:
-------------------------------
Since there may be many ways to describe the same task, and
some ways are simpler than others, the following additional
naming convention has been added for task documents.

Before the .seul or .html a number will be written to indicate
the complexity of the help. Command line commands are usually
a complexity of 1 (meaning most complex) while gui programs may
have higher values (indicating less complex). For example:

  Copying_a_file.1.seul
  Copying_a_file.2.seul

both illustrate how to copy a file except the first version is how
to copy a file using the copy command, while the second version is
how to copy a file using a file manager.