On Oct 25, 2012, at 5:07 PM, Peter Eisentraut <pete...@gmx.net> wrote:
> I think the emerging standard is to have a README.md (or something > similar). This gives enough structure and formatting options for most > extensions. For PGXN, I have used a README.md for a readme (briefly about the extension, how to build and install it), and a doc/$extension.md file for documentation on the usage of the extension. Quite a few people put all of that into the README, though. > I don't think we need anything fancy to install and access the > documentation. Most of the time it's on a server, in which case "less" > would do a good job. To me, it's more important to have the > documentation easily accessible over the internet for reference during > development. > > That said, we do have a built-in documentation infrastructure, which is > COMMENT. So an extension could have its documentation in its comment > and the comments on its subordinate objects. This may or may not > overlap with what a README would contain, but that depends on the > situation, I think. I think COMMENT is a bit lightweight for detailed documentation. I often write a lot of detail, including examples, summarizations, tutorials, etc., not just brief explanations of what each object is. Best, David -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
