Online publication systems

[Steven Owens <uso01 -at- MAILHOST -dot- UNIDATA -dot- COM>]

> As I mentioned previously, I'm currently in the position of developing a new
> documentation set entirely from scratch.  There is no existing documentation
> to model after, and I am responsible for defining style, content and
> delivery.

> One requirement is that the bulk of the information be delivered entirely
> online.  [...] the majority of customers prefer online documentation, with
> the caveat that it have excellent search and retrieval functionality).

        I'd suggest allowing boolean and regular expression search
capabilities if you can manage it (combined, if possible).

> I'm also very interested in the idea of having a combined documentation
> and training organization, and having materials come from this  "single
> source" of knowledge.  If the writer knows the material well-enough to
> write the books, shouldn' t they know how to teach the material?

        Ugh.  No.  Is knowing how to teach the same as knowing how to
write?  Is knowing how to write the same as being good with the
interpersonal skills necessary to stand up in front of the class and
teach the material, field questions, deal with the problems that occur
in the field?

        Writing coursework is not the same as writing user's guides.
(Speaking of which, anybody have opinions on coursework?).  We involve
both a writer and a trainer from the education department in
developnig coursework.  The trainer is generally working from regular
documentation that the writer developed (i.e. I wrote a manual on
system administration tools, and now a trainer is developing a
coursebook using that as source material - and I'm working with him).

> The information is the same, it's only the approach that's different.

        Then why not have the engineer write the documentation?  The
engineer surely knows the most about the product, and the information
is the same, it's only the approach that's different...

> The new scope of this project is related to this idea of a having a
> single source of information.  We (my manager and I) would like to
> create an online publications/"knowledge" system that will serve as a
> single source of product knowledge

        This is a good idea;  we're working on this at our company (where
the "Documentation" section became "Product Information" to connote the
idea that we gather and maintain information about the product, both to
produce documentation and to help make things run better inside the
company.

> Possibly also tied into this is the potential to easily create
> customized documentation for different customers/users.

        This is actually the concept behind SGML, Standardized General
Markup Language.  The format and organization of the text is divorced
from the content.  The content stays the same, but it's organized
differently.  Using the old paradigm you have to make a copy of the
entire thing, then massage the format and organization until you get
what you want (I had to do this recently - it's a serious pain).  With
the SGML paradigm (theoretically...) you can literally create new "views"
(to use your turn of phrase) of the data without changing the actual
data.

> I recognize that this is going to be an extremely complicated and
> expensive project, and I am only beginning to scope it out further and
> realize the many issues that will be involved.  Does anyone know of
> other companies that may have developed similar systems ?  (I imagine
> that this may be similar in some ways to SGI's Iris Insight)

Look into SGML.  I'm curious about Iris Insight (we're using an Iris
here).  What's it about?   Are there demos out there fore it?

Steven J. Owens
uso01 -at- unidata -dot- com