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.
|
