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

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

Josh Berkus wrote:
> Josh,
> 
>> 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
> 
> That's not accurate.  Pearson, for example, accepts LaTeX but not Docbook.

When I was speaking with Pearson (granted 2.5 years ago) they were
willing to accept DocBook.

> 
>> However, it is not a difficult requirement for developers to be expected
>> to document in docbook or to provide the user "manual" in docbook.
> 
> I disagree pretty strongly.  What Docbook lacks for some reason I've never 
> understood is any easy-to-use GUI tools.

You are sounding remarkably PHB every time you say that statement ;).
Seriously though, Docbook, especially DocBook simple, I would argue is
even easier than HTML. It is limited to only a subset of the full
Docbook spec.

However that being said, you are correct in that if we want to allow
users to user an editor that is not text based (VI, Emacs, BlueFish,
Kate) we need to pick something beyond DocBook.

I am kind of leaning toward OOo for the user manual, because it is
instant HTML, and instant PDF.

> 
> We need to use something which allows doc contributors to "just write" and 
> not need them to acquire specialized technical knowledge beyond knowledge 
> of LedgerSMB.   So, HTML, LaTeX, OO, wiki, whatever, but NOT Docbook.
> 

Well LateX falls into the exact same category as DocBook. Latex has Lyx
but AFAIK it is only one way.

What this basically comes down to is this. The chances of me submitting
any docs in Latex are about the same as you submitting docs in Docbook
(in either of our respective projects ;)).

So we are left with:

HTML, OO or Text. Wiki is great for community derived web docs, but not
for a manual.

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/