[FM Discuss] Documenting internals versus use (was: Beautiful Documentation with Sphinx)

[Andy Oram]

A lot of my work at O'Reilly covers APIs for various programming libraries, so I think it's great to do documentation for them. In my outline for the "Don't Flip" book, I point out that a topic may deserve good documentation even if the number of people who read it is small. That small number may be critical to developing new functionality for a project.

But I don't see much overlap between good API documentation and the stuff that Sphinx or javadoc manipulates. Those comments reflect the code from the inside out, not the outside in.

Andy

----- Original Message -----
From: "adam hyde" <adam at flossmanuals.net>
To: discuss at lists.flossmanuals.net
Sent: Thursday, March 12, 2009 6:21:58 AM GMT -05:00 US/Canada Eastern
Subject: Re: [FM Discuss] Documenting internals versus use (was: Beautiful	Documentation with Sphinx)

so far we have dodged the API bullet, janet took a few though and she
looked a little rattled ;)

im really not sure what we should do about this. as Anne said recently,
we are offering a toolset...so if someone comes along and says...i want
to doc my api...what do we do? i think we say ok

any thoughts?

adam




On Wed, 2009-03-11 at 12:10 -0400, Andy Oram wrote:
> I'd like to take the discussion of Sphinx, etc. up a notch. Is it part of FM's mission to help developers document their code? That's basically an issue of internals. I suppose some of these javadoc-type of comments are also useful for API documentation, but I suspect that serious API documentation must be generated with a more comprehensive, high-level view of the API.
> 
> The idea of embedding comments in each function goes back to Knuth's WEB, which never went anywhere but seems to be reinvented with every new generation of programmers and every language.
> 
> Andy
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
-- 
Adam Hyde
Founder FLOSS Manuals
German mobile : + 49 15 2230 54563
Email : adam at flossmanuals.net
irc: irc.freenode.net #flossmanuals

"Free manuals for free software"
http://www.flossmanuals.net/about


_______________________________________________
Discuss mailing list
Discuss at lists.flossmanuals.net
http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net

-- 
----------------------------------------------------------------------
Andy Oram  O'Reilly Media                     email: andyo at oreilly.com
Editor     10 Fawcett Street, Fourth Floor         voice: 617-499-7479
           Cambridge, MA 02138-1175                  fax: 617-661-1116
           USA                         http://www.praxagora.com/andyo/
----------------------------------------------------------------------