Jeff Hoffmann writes:
> has someone brought up the "annotated documentation" format like
> that's used on the php web site? i think it's an excellent
> combination of documentation, FAQ, and hints that makes it a lot
> easier to find answers than the standard "RTFM - read FAQ - search
> mailing lists".
As a PHP user I find that kind of helpful, because the PHP documentation
is really bad, or at least it was last time I looked.
As a PostgreSQL documentation writer I don't think this is such a good
idea. It would create all kinds of alternative, unchecked,
non-authorative information that would be distributed under the official
PostgreSQL banner.
If users have a suggestion, correction, or improvement for the
documentation, all they have to do is write us and someone will surely
integrate it.
Additionally, I imagine a number of technical and logistical problems with
this. The documentation is organized logically into chapters, sections,
etc., not in terms of HTML pages. Other formats (ps, pdf, dvi, man) would
not carry the benefit of these annotations. Even just a new stylesheet
for HTML might invalidate the whole database.
--
Peter Eisentraut peter_e@gmx.net http://yi.org/peter-e/
