Task Help

[Red Hat Linux User <twoducks@globalserve.net>]

Another old message

---------------
The following is something I whipped up. It is intended
to be a sort of proposal for a type of documentation that
is missing, and should? exist for SEUL.

Any comments?

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

Task Help - Proposal

Introduction

  The purpose of task help is to provide step by step instructions
  for small procedures. Unlike How Tos, which are long documents which
  may be complicated and detail many different tasks, the task help
  documents are quite small and written in a simpler style which can
  be understood by people who may not understand the details of UNIX
  and the utilities they may be running.

Goals
  There are several goals which should be kept in mind in the writing
  of task help:
  
  1. It should be written in a way such that the lay-person can
understand.
  2. All tasks should be short, simple (as possible) procedures.
  
Complexities

  There are some complexities which will be run into when writing the
task
  help. The main complexity is that of updating the help when new
programs
  are added.
  
  For example: The base task documents may include tasks for directory
  and file management (copying and managing files.) If the user installs
  a file manager they would want new task files which explain these same
  tasks through the file manager. What should be done with the old help
  files? What if more than one file manager is installed? What if the
  file manager is un-installed?
  
  This problem is more complex with different help topics.
  
  Solution
  --------
    The following is one solution which may be used:
    
    * Label the help files according to complexity levels: eg 1-5, 5 is
      least complex (or no max number, indicating things can always get
      simpler.)
      
    * Allow the user to display in the xhelp browser only those files
which
      are least complex (so the more complex ones are masked.) The user
can
      also display all help.
    
    * When new programs are installed (or uninstalled) the new documents
      may take over the view by being less complex (or stop being viewed
by
      being uninstalled).
    
    * Naming convention: mytask@1.html indicates mytask of complexity 1,
type
      html.