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

[David Tangye <..hidden..>]

I am in agreement with where you are thinking on all this, especially
the CMS idea: something I had also been thinking about, but I think I do
not have as much familiarity with CMS's as you.

A few points below:

On Thu, 2006-09-21 at 20:41 -0700, Chris Travers wrote:
> 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.
I guess I am thinking that context sensitive help is more valuable than
a document that is set up and whose strength is "for training people to
use the application effectively in a structured learning environment". I
would prefer to see the documentation effort targeting people who get
the product off the internet and want to use it. No corporate
hand-holding: no 'structured learning environment'.

> 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.
Can a CMS system contain info fragments, eg business rules, subjst areas
etc that can be cut and diced to form a bulk of both an online help and
a manual? I think so. So we have

 Base info -> online help -> edit/hack it -> generate to html
 same info -> user manual -> edit/hack it -> generate to latex -> pdf
etc

I see this being workable.

> 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.
Agreed. I forgot to say before: 'An advantage of a wiki is that anyone
can readily change it. A disavantage of a wiki is that anyone can
readily change it.' :-) Intelligent control is the key.

> What is needed is an editorial architecture.
Exactly.
> 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 fully agree.  In the long-term its the only way I see to stop a
support/wiki/documentation site becoming a total mess.
 
> ... an ability to ensure cosistancy across applications rather than merely the
> centralization of the data.
What do you mean here by 'across applications'?

>   But tehnology ought to support rather define community efforts.
Hmm. I think I am going to disagree. Unless you use the technology to
steer, ie define to some degree the community efforts you end up with a
mess, like what we are alluding to above. I would not be afraid of
saying, 'OK, based on what participants here have discussed and come to
agreement on, now *here is how we are going to do it*, and the software
will enforce it. Else why bother discussing it. Its too distracting to
have to explain/bitch/argue every time someone diverges. Better to
enforce rules, and have a separate area to discuss, amend,refine the
rules and change the enforcement facility to implement the new rules
where possible. 

BTW: Standards --> enforced/automatically applied standards = CASE
tools. This is where I spent the best part of 15 years.

> 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.
Agreed. Pleased you see it this way. A wiki just like a spreadsheet: its
immediate power is its long-term liability. It is great to start with,
but the more its used the quicker it can get out of control, and the
value of its content decline. Murphy's rule applies: the better
something seems initially, the worse it really is in the end.

> Furthermore, in the interest of keeping the barrier low, the user
> would not even have to know XHTML.
Agreed. I think we need to clearly differentiate 'user's:
  - developers/programmers,
  - analysts, domain experts (eg accountants), documenters other
development support people
  - system users

They all totally distinct groups of people with entirely different
focus, skills and needs.