Community Documentation Architecture, was LaTeX templates, was Docmentation/FAQs

["Chris Travers" <..hidden..>]

On 9/21/06, David Tangye <..hidden..> wrote:
> On Thu, 2006-09-21 at 14:24 -0700, Chris Travers wrote:
> > I think that backwards compatibility with LaTeX and easy
> > conversion from SQL-Ledger are going to require that we support it for
> > the forseable future.

> We, in this case meaning your company (inconsideration [sic] of your customer
> base), not this project?

Well, we as a project do want people to switch to our software, right?
I think it should be included with the project.

I don't mind taking ownership of the maintenance of it though.

>
<snip>
>  - at runtime a user wants help. A help button or whatever presents a
> context-sensitive help as another html page, eg a popup or window. From
> there links can jump the user to more general help, maybe two levels or
> it, the top level being the higher level info, eg from the "User
> Manual', such as the Best Practices info, the scope/high level
> description of the system/subsystem etc. So the user manual is just more
> html.

The current manual can be converted into HTML using LaTeX2HTML but it
isn't structured well for contextual help.  It was designed instead
for training people to use the application effectively in a structured
learning environment.  Also the manual is really designed to work well
as a training document and so I think that at the moment LaTeX or
possibly Docbook are better formats than HTML as the latter format
really isn't designed for printable media.

Personally I think a contextual help system would be great, but it
should be separate from a users manual  because the required structure
is just too different.  Obviously contextual help would need to be
primarily in HTML.

>  - The current user manual, and the results of these discussions all
> must go easily into a controlled repository eg a part of the wiki you
> are speaking about. The contents of this *is* the help system, whether
> its online or distributed is immaterial.
>
>  - The content is version controlled, eg under Subversion.

Agreed that all documentation should be effectively managed by
revision control.  Unfortunately this does raise some very difficult
issues.  For example, many HTML editors play havoc with version
control which means we would have a very short list of supported
applications (possibly only 1).

One possibility I have been suggesting is having a real CMS (not just
a wiki) for collaborative documentation.  A real CMS would give us
revision control etc. for all of these and we wouldn't have to worry
about graphical editors wrecking havoc on whitespace...

In fact, this seems to be about what you are descibing.
> A big problem I see with several other open-source projects is that the
> lists, wikis, 'user docs', 'user manuals' and god knows what else are
> all disjoint, and almost none are version controlled. Therefore you have
> to hunt all over the place to find a specific bit of info, and some info
> is contradictory because some bits get out of date; plus the doc gets
> out of date/step with the software.

Well, this takes a great deal more than just bringing these into a
central repository.  You have to have editorial control over a huge
repository of information which is rapidly changing.  It is not an
easy task.

What is needed is an editorial architecture.  Every bit of
documentation needs to have an owner who is responsible for the
editorial process.  This process needs to be technologically enforced
to the greatest extent possible.  I am evaluating a number of
applications for this, but the lead contenders seem to be out.  Typo3
requires MySQL and is not simple to set up on PostgreSQL, Bricolage
requires Apache 1.3.x.  There are a few other contenders, but they
seem about as open as SQL-Ledger....
> So lets set up a simple workable solution that ensures docs content is
> created easily, easily changed, easily managed, and is authoritative and
> correct, eg relates to versions of software where appropriate. Drop
> duplication, therefore merge the current manual into it, and ensure that
> there is only one master. dont set up a wiki before its clear how it and
> all documentation is to fit into one efficient picture.
Mostly agree but think there are a few things that need to be
considered.  The issue is editorialized control and an ability to
ensure cosistancy across applications rather than merely the
centralization of the data.  But tehnology ought to support rather
define community efforts.

> ps
> The thing I like about wikis is they are easy for anyone to contribute
> to, especially some with simple format rules, eg I have found any of old
> usemodwiki, twiki http://twiki.org/cgi-bin/view/Main/DavidTangye, or
> whatever Ubuntu uses is easy enough.

I don't think a wiki will cut it.  I think we need a real content
management system for all of the reasons you have enumerated above.

>  Tex/latex whatever:
> forget it.

LaTeX is very good for some kinds of tasks.  And I will not support
discontinuing support for it for PDF/PS generation for reasons of
ensuring that people can move to our software.  It is also by far the
best technology I have ever come across for maintaining large and
complex manuscripts.  I am sure Josh will disagree with me on this
point though.

I think it would be possible to create a Docbook to LaTeX mapping that
would preserve the most important mappings required for things like
indexes (the default Docbook way of maintaining an index is not
suitable for many environments and probably should not be used).  I
worry about how these would play with conventional editors though.

However, I am going to disagree with Josh a bit and say that neither
of these technologies is going to be suitable for community
documentation.  I think that the best solution is to have a real
content management solution that can export the content as XHTML.
> From here, it would be relatively straightforward to import that
either into LaTeX or Docbook via XSLT or someting similar.  THe
advantage here is that we only have a single editor, ideally with good
revision control, and an edforcement of editorial processes.
Furthermore, in the interest of keeping the barrier low, the user
would not even have to know XHTML.

At least it is something worth considering.

Best WIshes,
Chris Travers