[bind10-dev] about documentation

[JINMEI Tatuya / 神明達哉]

I believe I asked this before, but I'm still not sure about what to
do, so I'm revisiting it: it's about documentation of
design/API/implementation.

A quote from http://www.internetnews.com/infra/article.php/3824651

  "One of the goals for BIND 10 is to allow people to customize and
  extend without too much trouble," Shane Kerr, BIND 10's program
  manager at the Internet Systems Consortium (ISC), told
  InternetNews.com. "Every design decision will be documented in a way
  that makes sense without having to know the details of the entire
  system. The same applies to APIs and the code itself." 

That's fine and ambitious (although I hope we are not underestimating
how programmers are lazy about documentation:-), but what exactly am I
expected to document design decisions, e.g., for the DNS name class,
and in which format should I write it?

I recalled I've heard of google "designdoc"s, and found a link to a
live example:
http://docs.google.com/View?id=dfm7gfvg_0fpjg22gh

Following the style/organization of this example and arranging it with
our specific situations, we might have a document including the
following topics:

- Objective
- Background
- High Level Structure (design architecture?)
- API details (class/member function definitions and description)
- python binding (this would be a TBD item at this moment anyway)
- Test plan
- Security considerations
- Performance considerations
- Open issues
- References

Now, I have a question to Shane: is this something you imagined when
you said "every design decision will be documented..."?

Whether or not this is something we're expected to produce, I'm not
sure where and in which format we write it:
- is it documented in a separate file, or is it included as part of
  the source file (probably using some markup tools)?
- if it's a separate file, is it a plain text, or a html file, or an
  openoffice document, or something else?
- especially about the API details, would we embed it in the source
  file using a markup tool such as doxygen?  If yes, which tool would
  we use?

Another meta level question (or concern) is that how we maintain this
document.  As development proceeds, it's very likely that we see
difference/inconsistency between the initial document and the actual
implementation.  I suspect a simple rule like "try to update the
document in a best effort manner" won't work.  But at the same time,
a very strict rule like 'no document, no commit' wouldn't be realistic
either.  I don't know how other projects solve this problem, but if
there's a pragmatic example, I'm interested to look at it.

Regarding the maintainability, having a separate document would be
riskier.  For example, if we describe the API in a header file with a
markup, it would be relatively easier to update the description when
we change a function signature.  If it's a separate document, I'm
pretty sure the update will often be forgotten.

I don't think we need to have a perfect solution at this initial
stage, and I'm planning to do provide something anyway.  But if
someone can provide a good idea to address the questions and concerns,
that would be great.

---
JINMEI, Tatuya