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

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

I think we agree more than disagree here.  Are there any objections to
making our primary documentation system somethign that would be hosted
on a CMS?

On 9/22/06, David Tangye <..hidden..> wrote:

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

Horses for courses (no pun intended).  Contextual help is very
important but it is a big job that is going to require a lot of
community involvement.  However, I am a very firm believer that a high
quality training manual which is oriented toward teaching people the
software is absolutely indispensible.

One of the serious problems with most modern software is that they
assume that it should be easy enough to use that you should never need
to read the manual, and so they never write a decent manual.  Yet, if
you go back to the industry 15 years ago, you find amazing
documentation that allowed anybody to learn advanced concepts quite
quickly.  I have never been a fan of the software nor of their
successor company but the SCO System Administrators' Guide from 1996
is one of the best users manuals I have ever seen (it even beats The
FreeBSD Guide, if you can believe that).

> 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

Pretty close to what I am thinking but not quite.  HTML, Docbook, and
LaTeX all have the capacity to include different types of files, and
as long as the content as generated is XHTML compliant, you can do
transforms on it.

So you have:
Base info -> Generate to XHTML -> Online Help ->  Transform -> Docbook
-> Include in some large docuent -> Edit/Hack it -> Publish in variety
of formats

Base info -> Generate to XHTML -> Transform -> LaTeX -> Edit/Hack it
-> Include in some large document -> Publish in a variety of formats.

I think that there are clearly going to be clear cases where either
Docbook or LaTeX are superior to the other in terms of managing the
document

Because things like indexes and tables of contents should be generated
by the rendering program rather than stored in a
presentation-independant SGML document, it doesn't seem to me that you
lose anything other than the ability to have everything in one file.
Indeed, in this case, it would seem that the organization of the
document from the community resources would be the only big thing and
this would be necessary anyway.

Sorry, I meant across documentation endeavors.
> >   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.

Ok, I will admit to being pretty much a luddite wrt the use of
technology in this way.  I think that you want to have your editorial
process in place before you implement the CMS technology rather than
expect the technology to do it for you.  Same with CRM, ERP, etc.
These are all technologies that work best if they support existing
processes rather than acting as technological crutches.  The
technology may help you scale, and it may make you more efficient, but
it can't be relied upon to structure your processes.

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

No argument there though you have just suggested that we are actually
in agreement on the above points.

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

Again, technology supports the enorcement of the rules, but we should
define the rules rather than letting the technology do it for us :-)