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

["Joshua D. Drake" <..hidden..>]

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

I hate to say it... but Drupal is probably our best bet if we want a
community driven CMS. One of my customers employs a committer and I
understand the underpinnings pretty well.

In fact the first thing we do with Drupal (only take about an hour) is
rip out the search and plug in PostgreSQL + Tsearch2.

>> 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 power of wikis IMHO is the input type, not the wiki itself. We can
allow users to use ReST markup instead of HTML for their entries if we like.

>>  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 will not argue that LaTeX is good at what it does :). I will argue
this however.

For every person that is user LateX, there are a 1000 using XML and
specfically for technical documentation DocBook has taken over. Every
major publisher excepts *only* three forms of source for their material:

Docbook
OO (using MS Word Templates)
MS Word

My take on the whole thing is this. Within 6 months, migrating from
SQL-Ledger will be a no-op without a great deal of work. Within 6
months, we will have taken most of the users from that community, and
will have grown our community at least 10 fold.

Tex, needs to be deprecated and planned to be removed at some future
date but we need to give people the time they need. Say 2 years.

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

All you need is a transformation stylesheet, you can push DocBook as far
as you like.

> 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

Well it depends... When I think community documentation, I think
something people are submitting via the web CMS or wiki.

However, it is not a difficult requirement for developers to be expected
to document in docbook or to provide the user "manual" in docbook.

Sincerely,

Joshua D. Drake

-- 

   === The PostgreSQL Company: Command Prompt, Inc. ===
Sales/Support: +1.503.667.4564 || 24x7/Emergency: +1.800.492.2240
   Providing the most comprehensive  PostgreSQL solutions since 1997
             http://www.commandprompt.com/