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 <[email protected]>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 [email protected] > Software Designer, Fluid Project http://fluidproject.org > Adaptive Technology Resource Centre / University of Toronto > > _______________________________________________________ > fluid-work mailing list - [email protected] > 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
_______________________________________________________ fluid-work mailing list - [email protected] To unsubscribe, change settings or access archives, see http://fluidproject.org/mailman/listinfo/fluid-work
