Re: Extensions Documentation

On Oct 25, 2012, at 5:07 PM, Peter Eisentraut <peter_e(at)gmx(dot)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