Web based documentation

[Paul Lussier]

Cole Tuininga <colet at code-energy.com> writes:

> I'm looking for some suggestions (general or specific) with regards to
> web based software system for doing documentation.  The short story is
> that we have an in-house web based software project that we want to
> finally provide documentation for.  The basic requirements/wishlist goes
> something like this:
>
> * Must be configurable to require authentication to read it.  
>   - A plus: pluggable authentication so the current user database could
>             be used.
>   - A plus: If the requirement for authentication before hand could be
>             on a page by page basis.  In other words, some pages (or 
>             areas) would require it, others not.
>
> * Must have separate permissions for reading/writing documentation.
>   - A plus: If this was on a page/area basis.
>
> * CVS compatibility - If we're working on a big upgrade for the project
> that will involve lots of documentation changes, I'd like to be able to
> write the documentation before hand and deploy it at the same time we
> deploy the software updates.
>
> * Web based - needs to support "normal" browsers.

This is not exactly what you're looking for, however, I've become so
addicted to it, this seems a good time to plug this nifty emacs
extension :)

emacs-wiki is a series of emacs modules which allow you to essentially
create a wiki from flat, text files within emacs.  Since everything is
text file, version control is simple.  If everyone is using a text
editor, emacs or vi, then placing the source files within something
like CVS, SVN, ARCH, etc, is a no-brainer.  Or, a NFS mounted
directory.

The big win comes if using emacs, since the mode with auto-create new
page names just by selecting the WikiWord (though WikiWords are not
required for pages, emacs-wiki supports normal filenames, as well as
spaces in filenames).  Additionally, the mode has the ability to
publish the content in various forms: html, pdf, ps, etc.  Which
fulfills your requirement for the ability to view the content in
"normal browsers" :) Since the original docs are just files, you can
separate the permissions of read vs write.

There are even modules which can be added to provide authentication
using a Mason framework.

There's a pretty active emacs-wiki mailing list, and you can almost
always find someone on #emacs who uses emacs-wiki, or it's eventual
replacement muse-mode, as well as planner-mode, an emacs-based PIM
built on top of either emacs-wiki or muse.

I don't have a URL handy, but I'm sure if you search
http://www.emacswiki.org forg emacs-wiki under the HyperMedia
category, you'll find it.  Googling would be good too, google for
'emacs-wiki' and 'sacha' (she's one of the maintainers).

While I don't expect this to be what you're looking for, I hope I've
at least piqued the interest of someone here :)

-- 

Seeya,
Paul