[odf-discuss] print problem on Win XP (more info)

[marbux]

On 1/12/07, Daniel Carrera <daniel.carrera at zmsl.com> wrote:
> On Thu, 2007-11-01 at 23:01 -0800, marbux wrote:
> > I've never heard anyone complain about having too much documentation,
>
> Actually, in a way, it is possible to have too much documentation. Start
> with OXML's 6000-page documentation.

It still isn't enough to create an app that implements it fully. Tons
of binary blobs, Windows bitmasks, vendor-specific application calls,
and "compatibility" with completely unspecified binary file formats.
:-) But I know what you mean.

I've also complained about OOo's
> 120-page UNO documentation. Too much documentation can make it hard to
> find what you want, and is often a sign that you are not being concise,
> clear and relevant, so even when you do find the section you need you
> have a hard time figuring out what it says.

I'll still vote for too much if the choice is between that and too
little. But a lot depends on the complexity of what you're documenting
and the intended audience. E.g., documenting Windows Notepad is a
whole different thing than writing an owner's manual for a
telecommunications satellite.

There's a corrolary to Murphy's Law that says whatever particular bit
of documentation you need, you'll find anything but. Doesn't hold true
in all situations, but far too often. But a lot can be done by careful
documentation system design.

I favor task-oriented documentation for novice software users, i.e.,
How To-type materials. Once they've acquired competency and the
necessary vocabulary, then they're ready for the kind of reference
works that are more common classified by software features and
actions,  although even then a back-of-the-book style subject matter
index can really help.

I think one of the biggest failings of FOSS is that developers tend to
imitate Microsoft's approach to documentation systems in that
documentation development is largely reserved for documentation
specialists. E.g., far too often you have to learn to use special
software and coding to create an entire work. That's a major wart that
deals out most users, even the power users. Witness the OOo
documentation effort. Setting up a system where end users can easily
contribute doable hunks of documentation produces far more and better
quality documentation addressed to real world questions. For example,
the Drupal documentation -- using Drupal itself for documentation --
is much more complete than most projects that rely on Docbook etc. for
documentation.

There are some really exciting things that could be done using a CMS
for documentation. For example, some wikis enable automated
downloading of updated pages to a local system. See e.g., GetWiki,
<http://www.getwiki.net/>, a fork of MediaWiki. If an end user clicks
on a wiki link and there is no corresponding page already in
existence, GetWiki branches to another wiki, and if it finds a page
with that name, automatically imports it. It can also be set so that
if a page by the same name exists on both the local and remote wikis,
the most recent will be used/imported.

So a user might, for example, easily contribute documentation on a
remote wiki. Other end users could then have their local documentation
automagically updated on demand.

Lots of possibilities. But I would generally favor any solution that
as a practical matter gives end users a bigger role in the creation of
software documentation. My experience administering a tech web site
says that if you make it easy for folks to contribute chunks, you get
a lot more participation in documentation development than you do
limiting development to the favored few who use specialized tools.

Best,

Marbux