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

[adam hyde]

>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.
> 

sounds good to me

On Thu, 2009-03-12 at 08:54 -0500, Janet Swisher wrote:
> 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
> _______________________________________________
> 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