Documentation: keep it close, keep it current

Documentation

Everyone hates to write it
Everyone loves it when they need it
The pleasure of a well-written man page
Examples: --help, man page, perldoc

Good documentation must be:

Easy to write
Enforced socially
Enforced technically
Automatic as possible
Tested and used

Easy to write

- Standards
- Examples
- Interfaces and tools

Enforced socially

- It's a dirty job
- Making it fun

Enforced technically

- The nag factor
- Don't just encourage, enforce
- Smoke testing

Automatic as possible

- Creation, modification, review, collation

Tested and used

- Share the burden (QA)
- Auditing


SELECT man('validate_ccnumber');

Getting there

First solution: the comment field
COMMENT ON table dual IS 'This table is an ugly hack'
Available for all objects
Too generic - a single text field
This is a database after all


CREATE TABLE manpage (
  relation      oid,
  created_on    TIMESTAMPTZ NOT NULL DEFAULT now(),
  created_by    TEXT,
  last_modified TIMESTAMPTZ NOT NULL DEFAULT now(),
  summary       TEXT,
  description   TEXT,
  input         TEXT,
  output        TEXT
);

Result:

Still fairly free-form, but with a little more structure
It is a little raw, so we will make a view for it
Note how the relation column expands into all sorts of other information:


CREATE VIEW man AS 
  SELECT n.nspname AS schema, c.relname AS "name", c.relkind AS kind,
    m.created_on, m.created_by, m.last_modified, m.summary, m.description,
    m.input, m.output, relation_version(n.nspname,c.relname) AS version
FROM manpage m, pg_class c, pg_namespace n, pg_type t
WHERE m.relation = c.oid
AND   c.relnamespace = n.oid

System catalogs

By directly linking to the system catalog, we allow good documentation to be created
The magical version function: cvs/subversion interface
SELECT man('valid_ccnumber');
SELECT man('public.valid_ccnumber');

Back to the comment

Automatic insert on doc creation (triggers)
COMMENT ON TABLE dual IS 'Please do a SELECT man(''dual'') for full documentation';
More triggers: index, HTML, XML, etc.

Technical enforcement

Is everyone playing nicely?
SELECT mancheck();
SELECT mancheck('schemaname');
SELECT mancheck('schemaname','object name');
Checks all user tables, views, function, triggers, domains, and operators
High details not necessary, except for functions
List the applications that use it, important dates, etc.
Also (or?) in the cvs logs for the schema
Enforcement: man -> mancheck

Close to the data

Better than cvs
Documentation lives close to the data
Exported with the data
If data is available, docs is available
Language independence