As páginas de referência devem seguir um modelo padrão, permitindo aos usuários encontrarem as informações desejadas mais rapidamente e, também, para incentivar a quem escreve documentar todos os aspectos relevantes do comando. A consistência não é desejada apenas entre as páginas de referência do PostgreSQL, mas também com as páginas de referência fornecidas pelo sistema operacional, e outros pacotes. Por isto, foram desenvolvidas as diretrizes mostradas a seguir. Elas são, em sua maioria, consistentes com diretrizes semelhantes estabelecidas por vários sistemas operacionais.
As páginas de referência descrevendo comandos executáveis, devem conter as seções na ordem mostrada a seguir. As seções que não se aplicam podem ser omitidas. Seções adicionais de nível superior devem ser usadas apenas em circunstâncias especiais; geralmente esta informação pertence à seção “Utilização”.
Esta seção é gerada automaticamente. Contém o nome do comando, e um resumo de meia frase de sua funcionalidade.
Esta seção contém o diagrama da sintaxe do comando. A sinopse normalmente não deve listar cada opção de linha de comando; isto é feito abaixo. Em vez disso, devem ser listados os principais componentes da linha de comando, como para onde vão os arquivos de entrada e saída.
Vários parágrafos explicando o que o comando faz.
Uma lista descrevendo cada opção da linha de comando. Havendo muitas opções, podem ser usadas subseções.
Se o programa usar zero para sucesso, e diferente de zero para falha, não é necessário documentar. Havendo um significado por trás dos diferentes códigos de saída diferentes de zero, então devem ser documentados aqui.
Descreva qualquer sublinguagem, ou interface de tempo de execução do programa. Se o programa não for interativo, esta seção geralmente pode ser omitida. Caso contrário, esta seção é um resumo descrevendo os recursos de tempo de execução. Use subseções, se for apropriado.
Liste todas as variáveis de ambiente que o programa pode
usar.
Tente ser completo; mesmo variáveis aparentemente triviais,
como SHELL, podem ser de interesse do usuário.
Liste quaisquer arquivos que o programa possa acessar implicitamente, ou seja, não liste os arquivos de entrada e saída que foram especificados na linha de comando, mas liste os arquivos de configuração, etc.
Explique qualquer saída incomum que o programa possa criar. Deve-se evitar listar todas as mensagens de erro possíveis. Isto dá muito trabalho, tendo pouca utilidade prática. Mas se, digamos, as mensagens de erro tiverem um formato padrão que o usuário possa analisar, este seria o lugar para explicá-lo.
Liste quaisquer arquivos que o programa possa acessar implicitamente, ou seja, não liste os arquivos de entrada e saída que foram especificados na linha de comando, mas listo os arquivos de configuração, etc.
Exemplos
Havendo alguns marcos importantes na história do programa, eles podem ser documentados aqui. Normalmente, esta seção pode ser omitida.
Autor (usado apenas na seção contrib)
Referências cruzadas, listadas na seguinte ordem: outras páginas de referência de comandos do PostgreSQL, páginas de referência de comandos SQL do PostgreSQL, citação de manuais do PostgreSQL, outras páginas de referência (por exemplo, sistema operacional, outros pacotes), outra documentação. Os itens no mesmo grupo são listados em ordem alfabética.
As páginas de referência que descrevem comandos SQL devem conter as seguintes seções: Nome, Sinopse, Descrição, Parâmetros, Saídas, Notas, Exemplos, Conformidade, Histórico e Veja também. A seção Parâmetros é como a seção Opções, mas há mais liberdade sobre quais cláusulas do comando podem ser listadas. A seção Saídas só será necessária se o comando retornar algo diferente de uma marca de conclusão de comando padrão. A seção Conformidade deve explicar até que ponto este comando está em conformidade com o(s) padrão(ões) SQL, ou com qual outro sistema de banco de dados é compatível. A seção Veja também dos comandos SQL deve listar os comandos SQL antes das referências cruzadas aos programas.