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

[Janet Swisher]

Just to clarify -- Sphinx is not an API-doc generator like Javadoc,
Epydoc, or Sandcastle. It is a tool for converting book-structured
text files into formatted output. It has hooks for importing
docstrings, but using it to generate API doc requires a bit more work
than a generator-type tool. The Python docs, for example, have a lot
of "outside-in" content, such as tutorials.

To your larger question, this gets at the "mission, vision, and
values" issue that we flirted with at Winter Camp, but did not
directly address. My understanding of the mission of FLOSS Manuals is
that it is to help people use free software by providing them with
free documentation. Our focus thus far has been on "end-users", but
they are not the only users of free software. A large category of free
software is libraries, where the users are programmers creating larger
applications; they also need documentation, because there is always a
gap of understanding between the programmer who wrote the code and the
programmer who is just using the code. However, that gap is typically
not as large as the gap between programmers and end-users. Therefore,
I think we should concentrate our efforts on end-user documentation,
while still allowing/supporting use of our tools for free software
documentation of any kind.

--Janet

On Thu, Mar 12, 2009 at 6:50 AM, Andy Oram <andyo at oreilly.com> wrote:
> 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