documenting contrib modules (was Re: Building PDFs error)

On Sat, Mar 12, 2011 at 3:57 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Peter Eisentraut <peter_e(at)gmx(dot)net> writes:
>> On lör, 2011-03-12 at 09:13 -0500, Bruce Momjian wrote:
>>> OK, it is not something worthwhile, or just something you don't have
>>> time for.  If the later, can you give us a hint on how to fix it?
>
>> I'm not even sure what the actual action item is supposed to be.
>
> The last suggestion in the thread was to move the contrib docs up one
> level in the hierarchy, ie each contrib module would get a chapter not a
> sect1.

Trouble is, many of those will be extremely short chapters. Consider
passwordcheck, for example.

I think that contrib has a bit of a split-personality disorder at
present. It has at least four different kinds of things in it:

- First-class citizens intended to provide core functionality
(file_fdw, pg_upgrade, dblink, hstore, sepgsql, pg_archivecleanup)
- Debugging and instrumentation tools (pageinspect, pg_buffercache,
pg_rowlocks, pg_stat_statements, auto_explain, oid2name)
- Code examples, some of which are also used for regression testing
(spi, dummy_seclabel, test_parser)
- Modules that are largely superseded by new core features, but we
can't quite bring ourselves to kill them yet because they still have
some possible remaining utility (xml2, intarray, intagg)

I think it would be really helpful to try to group these modules in
some way, and perhaps provide a chapter for each group rather than a
chapter for the entire set. If you're looking at contrib for the
first time, it's pretty hard to know that the thing called hstore is
something many people think is teh awesome while the thing called
intagg is a compatibility wrapper with no obvious residual utility
whatsoever. Arguably we should try to rearrange the actual source
code tree at some point, too, but maybe that should left for phase 2.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company