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

[Jacob Farber]

Perhaps its time we look to a dedicated help management system, not just a
comment scrubbing one? Im thinking something off the shelf like RoboHelp (I
know I know, Adobe = A little Evil)
Other than that, maybe we just author some XML files and output + reformat
that to whatever sources we need (eg. wiki, pdf, html, etc)?

None of the above sound ideal.....


On Thu, Mar 5, 2009 at 5:26 PM, Anastasia Cheetham
<a.cheetham at utoronto.ca>wrote:

>
> We recently decided that we would move to auto-generated API documentation
> produced from comments inline with the code (see discussion on the list
> titled "Autogenerated API documentation", started February 20, 2009).
>
> I have been researching and playing with various tools for this, but I had
> a bit of an epiphany this afternoon, and I think we need to re-think this.
> I'd appreciate everyone's thoughts.
>
>
> Our components are highly configurable - it is one of our primary
> strengths. This configurability means that we provide implementors with a
> variety of options for customizing a component. Explaining these options in
> documentation takes words - often, quite a number of them.
>
> As an example, have a look at the List Reorderer API page:
>    http://wiki.fluidproject.org/display/fluid/List+Reorderer+API
> This is a relatively straight-forward component, with a typical amount of
> available customization.
>
> Here's the crux of the problem I'm seeing:
> If we want to be able to automatically generate a page that includes all of
> this information, then *all of this information will have to be in the
> comments of the JavaScript file*. I think that having this much text in the
> file will make it completely unreasonable to work with.
>
> Additionally: The List Reorderer is one of several flavours of the
> Reorderer. Internally, all of the different flavours exist in a single
> JavaScript file. I can't even begin to imagine how we could coax an
> automated system into producing 5 different pages from a single file, each
> with different but overlapping subsets of the information. We would have to
> split the JavaScript itself up into multiple files, for a start.
>
> And the Reorderer is not the only component that presents this issue. The
> Inline Edit has a number of configuration; the Uploader has several
> alternative subcomponents; the Pager has several alternative
> subcomponents...
>
>
> My fear is that any automatically generated documentation will lose the
> cohesiveness that I think is a strength of what we've got now.
>
> Does anyone have any suggestions??
>
> --
> Anastasia Cheetham                   a.cheetham at utoronto.ca
> Software Designer, Fluid Project    http://fluidproject.org
> Adaptive Technology Resource Centre / University of Toronto
>
> _______________________________________________________
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://fluidproject.org/mailman/listinfo/fluid-work
>



-- 
Jacob Farber
University of Toronto - ATRC
Tel: (416) 946-3002
www.fluidproject.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://fluidproject.org/pipermail/fluid-work/attachments/20090305/d5a21acf/attachment.html>