[bind10-dev] API documentation (was Re: DNS packet API: the name object)

[Jeremy C. Reed]

On Tue, 18 Aug 2009, Jeremy C. Reed wrote:

> From our summer 2009 BIND 10 meeting:

Found more of my notes (discussed on different days)...

generate HTML (sane and useful), PDF, book, ROFF/mandoc

docs for current code and proposed code?

API become book

man pages -- don't be redundant (don't write same docs twice)

tools be self documenting
like postconf but better
like NetBSD sysctl showing descriptions
like FreeBSD "pw help" or NetBSD "user help"

editors/tools for maintaining docbook
(some are listed on http://bind10.isc.org/wiki/Documentation )

problems:
- third party generator tools
- written by original implementor

have documents owner -- even for style guide
date, time to live, when to revisit/review

TODO: styleguide for docs, blog, review ...

TODO: instructions on how to do docs:
- simple install
- simple tags (like for docbook)
- simple regeneration (generate HTML, etc)
- simple upload/redistribution of documentation

Trade journals

Code review include "documentation" checkbox

Coherent release notes for manager/high levelk with reasons

Blog -- one new article per week
- rotation for who can write (maybe everyone will write once every 8 weeks 
or so)

generate pages for wiki?

API book

docbook can generate UML diagrams?

TODO for API guide: "how to make a module" documentation