A r t i c l e s
Navigation

Note: This Wiki is
outdated, personal views
may have changed.
L505 A.I. bot is dead
long live THX 1138

M a i n P a g e

D i r e c t o r y

LufDoc


For an example of LUFDOC in the real world, see
Live User Fed Documentation
See also: LufDoc Tools
LufDoc is based on the idea that both users and developers should contribute to documentation of source code and/or other projects, in a live, real time manner. Instead of users being given a help file, zipped help files, a binder or book, PDF or html files, which are fixed or hard to modify on the fly, LufDoc encourages live, real time modifiable documentation.
Users can patch, update, and easily modify the documentation. LufDoc encourages users to modify the documentation and contribute to it, because sometimes the majority of quirks and examples for a project are discovered and created by users - not just developers.
LufDoc will work with tools like FPDOC and other source code generating tools. FPDOC can be the core generator for example, while the LufDoc tools can add on to the core and take care of the live system. Instead of a user requireing to compile a descriptor file while generating the core, he can utilize a live documentation system.
LufDoc Core and LufDoc Additions

LufDoc consists of the core and the additions. The core is usually the part of the documenation that is automatically generated from source code. This is the part of the documentation that users rarely need to change. The lufDoc additions are examples, tips, descriptions to the help files that compliment the core, and make up most of the documenation.


In order for a user to update and contribute to documentation of a project, the documentation must be:
 -easily available. Online through a thin client or browser is preferred. A large 
  download file is not preferred. Rather the documents should be separated into 
  sections and files. 12MB HLP or ZIP files that need to be recompiled or repacked 
  each update are an example of poor documentation formats. Those can work well as
  snapshots of documetnatoin at a certain period of time, but not for real time 
  ongoing updates in an active project. 

 -easy to update. See above.

 -split into a core section and an addition section. The addition section will 
  contain additions, tips and examples from users. The core section will be generally 
  created based on sources or hard text that generally stays the same (i.e. core of 
  the documentation stays more fixed, and the additions change and get updated. Some 
  times the core needs to be updated too, but less often than the additions ).

 -easily generated. Users will not neccessarily generate the core documents, but 
  rather add to them. Users should not have to regenerate the core each time they
  want to make a simple note or addition to the help document. If a user thinks the 
  core document needs to be changed (i.e. due to an error) he can even make an
  explicit note to do so in the addtions section. This encourages casual users 
  passing by to help solve errors, while traditional documentation methods
  discourage users to help solve errors (because it's too much work to send an
  email, ask about the error, ask about making a patch to the docs, etc.).

 -updatable on the fly. A casual user should be able to post a tip or offer and 
  example on the documentation subject he is reading about immediately while he is 
  already there reading about it. Capturing the user while he is already reading the 
  documentation, encourages him to assist with the docs when his attention span is 
  high.  The LufDoc captures this opportunity - making it easy for the 
  user to post his example or tip that he discovered after reading the docs. (similar
  to a wiki, where it is easy to edit in the moment, in real time. Not later, after,
  or some time soon. Present, now.)

Tools:

LufDoc offers CGI programs and thin client software for users that see the advantages of live documentation. If you wish to use LufDoc on your software or other project, there will be tools already available or you can upgrade them and create your own customized versions.


LufDoc prefers documentation via the web through thin clients, TCP/IP enabled software, and web browsers due to the fact that they are live and cooperate with the philosophies of LufDoc well.

For the casual user browsing the internet who finds a help file posted online, LufDoc believes that this user should be able to update and modify the document if he finds the document lacking. In a web browser, it will be convenient through a CGI program for the user to do this. If the user needs more advanced editing features, he will be offered thin client tools or other TCP/ip enabled software to modify the document. This helps break the barriers of web browsers, such as poor editing capabilities and other obvious HTML restrictions. The base document files will be stored in the same place, on a server. The thin client or the web browser connect to the documentation files and parse them into the browser or the thin client. The thin client may parse the document differently than the CGI program, in order to offer more flexibility than an HTML web browser. The document may be in a common format such as LaTex or PasWiki syntax, which is created into html in a web browser, or into GUI components on a thin client (memo's, edit boxes, RTF, HTML widgets, etc.)


LufDoc discourages
 -documentation based on PDF files, since they are hard to easily modify for the 
  casual user passing by. If a user wishes to print his documentation he may 
  convert his help files to  PDF at that period in time, but PDF should not be used
  as a basis for the format of the documentation.

 -static html. The docs should be on a live site with a CGI program installed where 
  the html can be updated. Fixed help files in HTML are not easily modifiable and
  cannot be updated in real time.

 -html Less than Greater than syntax. The documentation should be easy to write. 
  Syntax such as PasWiki  syntax or BBCode style square bracket HTML is better 
  than lessthan/greaterthan HTML style.  On a qwerty keyboard, less than and greater 
  than signs are a pain in the butt to type over and over again due to thier shift 
  key reliance. We want to encourage folks to edit the documentation, not discourage 
  them and cause them finger arthritis.

 -documentation that requires a recomipile with every change. The users should be
  able to contribute and add to the documentation immediately. Documents should be
  recompiled or generated only every so often - such as if a major change is being
  made to the core documention. The users should not have to download document tools,
  compilers, and waste valueable time fiddling instead of contributing to the docs
  when their attention span is high. Yes, the core docs can be recompiled, but quick
  patches, tips and updates to the docs should be quick, easy and Live.

Typical problems with traditional documentation:
 -books, CHM, HLP files, PDF, and static HTML files quickly become outdated and 
  obsolete.

 -examples from the original developer who created the documentation are not thorough
  enough.

 -developer is not in the user's shoes. The user is using the help docs more so than
  the developer. 

 -the user some times knows more than even the developer on specific subjects

 -the user may have an example of his own which describes the help text many times
  better than in the original documentation

 -the user loses interest when he has to send mail to a mailing list to ask if he
  can update the help docs. The user should be able to modify the documents on the
  fly, or make additions on the fly.

 -the user loses interest when he has to go through extensive hassles just to change
  or update one small issue in the help text. This is similar to the idea of one 
  click shopping or credit cards. People do not have time to get a check, get a
  stamp, mail a letter, send emails, make phone calls. Rather, a convenient and 
  effecient experience is preferred. 

 -the user does not have time to spend an hour finding out who and how to update
  the help text. It should be obvious and changes should be possible immediately
  through self serve. 

The self serve philosphy of LufDoc is similar to a wikipedia, in that the visitors and users update the docs. However, LufDoc is more geared toward documenting software programs and projects, whereas wikis and wikipedias are for general discussion.

LufDoc encourages a combination of some direct editing to the major portions of the help documents (core), but also encourages "additions" to the documents. Additions in LufDoc can be kept separate from the core, where as a wiki is generally combined as one large document. LufDoc has tools and aims for software documentation, whereas wiki's and discussion forums are more general purpose systems to talk, chat, and discuss.

About
Note: This Wiki is outdated, personal views may have changed.

This wiki contains info on life, health, humans, nature, programming, database, fads, paradigms, poems, principles, theories.

Articles may contain statements which some may find helpful and encouraging, or even discouraging.

Beware, I believe in the Grand Justice system.
_ _ _