httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject Antwort: user annotations (was: [STATUS] (httpd-docs-2.0) Wed Oct 16 23:45:26 EDT 2002)
Date Fri, 18 Oct 2002 12:03:21 GMT

Hi Andy,

>> Just as an example: The mySQL documentation at
>> (just some example URL, applies to the whole document tree)
>> is offered in a way that users may add comments to each and
>> every page of the online manual - most likely to the one
>> where they believe this information should be found.
> This would probably require some major docs format changes.
> For example, take mod/core.html. It's long enough. Where should
> the user annotations appear? We could split the documents.
> One page for a directive. For user contributions perhaps a
> better design, for most readers a nightmare, I think.

my main goal was to _not_ require the docs maintainers to make
_any_ format changes.
If such a specialized presentation of the Apache documentation
would work better with individual files for each directive,
then treat this presentation as a separate product, and make
them use the Apache documentation "as is" being fed into what-
ever transformation process they require.
The better structured the Apache docs sections are (and they
are structured _very_ well now, due to the systematic use of
XML and CSS!), the easier it will be to write some tool to
split up core.html into individual files.
(The "self portal" search engine is doing just that when
indexing "chapters" instead of URLs, relying upon knowledge
about the basic document structure and "validating" it during
the process.)

Actually, I am just letting my thoughts flow.
We now have an Apache documentation in XML format. This would
provide some structure that would easily allow for different
presentations of the documentation.
Now _are_ there any ideas for different presentations of the
documentation (now focussing not on the layout, which is CSS
territory, but on the functionality of the documentation, like
being able to write feedback, having a search form available
in every document and these things) - or is the current docu-
mentation already good enough to concentrate on other things?
_Is_ there anything that could directly benefit from the fine
new structure the Apache documentation has got now?
(And I would definitely accept "no" as a valid answer. ;-)

> I'm not sure, whether the mysql or php way of user annotations
> is the best one. If I take a look at the user comments, my first
> thougt is: no.

Maybe this could be some project that someone might run for
his own fun, on a separate site, just to collect feedback
from the users.
If such a project would not require the docs group to do
anything special for their support, then it might just
experiment on its own, and mainly exchange experiences and
feature requests with the docs group.
And if finally the whole thing would surprisingly prove to
be of any use, then the Apache Group might still decide to
run it on their server as well.
But as I know that maintaining the whole thing is important
for the Apache Group, I just want to brainstorm which requi-
rements this might mean for any product, whether already
existing of being created.

> Just an idea bubbles up at 02:50 in the morning: links at every
> directive (in the module docs) and on every other page to a
> *simplified* form, which receives some user input and puts it
> to bugzilla or elsewhere (e.g. mail). We (the committers) or
> at least some of us are responsible for evaluating the stuff
> and building in or rejecting or whatever one can do with it ;-)

Fine. If there is some feedback tool already, just make it
available to the readers as easy as possible.
Not many of them will know the whole bunch of features that has to offer - many will request individual pages
because of deeplinks being followed, or even search engine

And making some Apache handler generate links to Bugzilla
into an Apache docs content on the fly is probably even much
easier than the thing I described in my previous mail.

Regards, Michael

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message