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

[David W. Hankins]

On Fri, Oct 09, 2009 at 12:24:30PM -0700, JINMEI Tatuya / 神明達哉 wrote:
> > Look at PHP documentation examples:
> > http://www.php.net/manual/en/
> > http://www.php.net/manual/en/language.namespaces.definition.php
> > One thing that is interesting is that it includes "add a note" for "User 
> > Contributed Notes" with feedback for examples and experiences appended to 
> > end of official docs.
> 
> This seems to be an interesting idea.

I would be very happy if our documentation (especially our API
documentation) wound up looking like php.net.

My only warning is that php.net's webpage looks like a blog, but it
was created before the word 'blog' became a thing.  They couldn't just
go and fetch some blog software - they had to write PHP first so that
blog software could later be written.  Would they have done all that
starting over today?

Similarly, their webbed documentation looks like a "post with comments
page", and this again predated Wiki's.

At the first DHCP Forum meeting held at a LISA, real actual users had
something to say about this, and it was: "Wiki.  Not PHP.net."  The
sample set is small, and the audience would mainly digest
configuration documentation not API, but we should be careful to
remember that the customer for or documentation is not us (and the
customers for different types of documentation are different).

I don't know if there is any readily available Wiki software that has
a construct that allows an enforceable separation between the
"official" and "user submitted" documentation.  There are at least a
few software packages that claim to be intended for software
documentation.  The only one I tried (the first one I found) does
support 'section editing' but applies ACL's on a page-by-page basis,
so it wouldn't do quite what we need.


Anyway, like PHP.net, I don't think we should be afraid to extend an
existing project or invent something new (so long as it is simple, at
least at first) to get the Right Thing.  The 'S' in ISC used to stand
for Software after all.

-- 
David W. Hankins	"If you don't do it right the first time,
Software Engineer		     you'll just have to do it again."
Internet Systems Consortium, Inc.		-- Jack T. Hankins
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: not available
URL: <https://lists.isc.org/pipermail/bind10-dev/attachments/20091012/a6cf9995/attachment.bin>