Re: LaTeX templates, was Docmentation/FAQs

[David Tangye <..hidden..>]

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 of your customer
base), not this project?
> 
> We could, however, offer plugins to support alternatives.
> 
> However, a few points:
> 1)  We really ought to revise the LaTeX of the templates to be less
> braindead and brittle.
> 2)  We need to make the templating system LyX-friendly
> 3)  We should allow the calls to the templates to hit a different
> extension for the template and a different executable to allow for
> plugins of this sort.

I have been meaning to write this for a couple of days.

I think that the entire documentation and support system could be
streamlined. As always, I apply the fundamental of 'Quality': 'Customer
Focus', and so suggest in this order:

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

The best technologies to use should become apparent after we think about
this complete picture, plus weigh up other specifics mentioned by others
in the past day.

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.

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.

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. The idea of discussion pages for
each wiki page has merit, as long as this sort of discussion shifts to
there with only a 'heads up' being flagged on here. Tex/latex whatever:
forget it.