Documentation: To auto-generate, or not to auto-generate?

[Anastasia Cheetham]

On 6-Mar-09, at 2:20 AM, antranig at caret.cam.ac.uk wrote:

> although auto-generated documentation can
> never be an adequate replacement for a complete manually written
> component guide, it is no reason not to have some....I don't think
> anyone is suggesting that moving to autogenerated docs implies
> destroying pages like "List Reorderer API" and their kin? Those
> were an awful lot of work to produce that indeed it would be silly
> to stuff into a single .js file

Yes, lots of work *did* go into creating those pages!! I'd love to  
find a way to not waste all that effort.

Ok, so lets follow this though a bit: Suppose we have autogenerated  
API docs, as well more detailed explanations elsewhere.

Sticking with the List Reorderer API page as our example, there is  
information on that page which would be duplicated by autogenerated  
API docs, i.e. the function signature and basic parameter  
descriptions. Would we remove that info from the wiki page? If we  
didn't, then we'd have duplicated information that would need to be  
kept in sync.

We would still need to deal with 'release' vs 'trunk' versions of the  
wiki pages. As the API settles down and changes much less often, this  
will become easier. And if we don't continue to maintain past  
versions, but simply have trunk and release, it would be much easier  
to simply keep the trunk versions up-to-date as we work, then at  
release time, replace the older release version with a new snapshot.

Also, we'd need links between the auto-generated API page and the more  
detailed explanations on the wiki. At release time, when a snapshot is  
taken of the trunk wiki pages, links there to the trunk API docs would  
have to be updated to reference the release version. Also, any links  
in the autogenerated docs to the wiki would have to be referencing the  
correct version of the wiki docs.


All of these 'versioning the wiki docs' issues would be much  
simplified if the manually created docs were not on the wiki, but also  
in SVN in some format, e.g. HTML, XML, etc. Perhaps Markdown might be  
of help here:
     http://daringfireball.net/projects/markdown/

-- 
Anastasia Cheetham                   a.cheetham at utoronto.ca
Software Designer, Fluid Project    http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto