In my opinion it is far too early to
decide on whether DocBook or
OpenOffice etc would make the most practical
standard format
for ObjectWeb documentation.
Why is it too early?
Because we did not put down any requirements
a documentation format must meet.
If we have no accepted list of requirements
we can't use
clean-cut arguments like
* "Format F is no good because
it does not address requirement R".
* "S1 covers all critical requirements".
(2)
Aside from the documentation standard
format itself
we must take into consideration the
processes involved
to maintain documentation.
We must do a lot better on redactional
process support
than most newspapers do today.
To focus on the first edition only,
and not giving careful thought
to all the use cases that affect documentation
and which documentation is part of
will make us end up with a standard
that will not serve our needs.
Claus
Hirth
Diplom-Informatiker
Universität
Documentation Standard Requirements,
claus . hirth
