What should we do about API documentation?

Allison Bloodworth abloodworth at berkeley.edu
Tue Jan 20 21:22:45 UTC 2009


I'm not sure how many folks out there have experience with DocBook,  
and it's been a while for me but I did write the initial specification  
for the UC Berkeley Calendar Network in DocBook (http://ets-dev.berkeley.edu:8901/EventCalendarSpec_v0.5/ 
). I used the XML Mind Editor (http://www.xmlmind.com/xmleditor/) to  
write it. As I recall there was a bit of a learning curve, but I was  
pretty happy with what I could do to present the information after I'd  
learned the app, as well as all the documentation formats that could  
be produced. There is a personal edition of XML Mind that's available  
for free, but having to download and install it (or alternatively,  
navigate the XML without an editor) would certainly raise the barriers  
to entry for contributing to documentation.

On Jan 16, 2009, at 4:36 PM, antranig at caret.cam.ac.uk wrote:

> Well...perhaps straight "something" + SVN. In several cases I am  
> actually
> resorting to plain HTML + CSS in our documentation since getting
> sufficient control over Confluence markup is essentially impossible  
> for
> more complex table scenarios. We should probably look into more
> specifically relevant solutions though, such as DocBook or xdoc/Apt -
> one very frequent request I had with RSF was for a "single narrative"
> form of the documentation that could be printed out and studied
> offline, and this could be something well worth starting out with
> with Fluid.
>
> Something like this?
> http://doc-book.sourceforge.net/homepage/
>
> Can we afford this level of change to everything?
>
>
> Quoting Justin <justin.obara at utoronto.ca>:
>
>> Some questions
>>
>> 1) Would that mean creating a docs.fluidproject.org site? Would this
>> link to the trunk docs or the  docs for the last release?
>>
>> 2) Would that mean that the docs would be included in the release
>> bundle?
>>
>>
>> - Justin
>> On 16-Jan-09, at 2:25 PM, Anastasia Cheetham wrote:
>>
>>>
>>> On 16-Jan-09, at 12:19 PM, Michelle D'Souza wrote:
>>>
>>>> 5. Move to another strategy altogether for creating and versioning
>>>> API docs. Suggestions?
>>>
>>>
>>> I actually think we're reaching a point where we need a new  
>>> approach.
>>>
>>> My suggestion:
>>>
>>> Straight HTML+CSS, in SVN.
>>>
>>> Benefits:
>>> Built-in versioning; versioned docs can be bundled with a release;
>>> versioned docs can be easily served up on a public site; much
>>> greater control over the appearance of the docs (through CSS).
>>>
>>> Issues:
>>> Slightly more cumbersome edit/share process than the wiki: HTML  
>>> mark-
>>> up instead of wiki, SVN commit/update cycle necessary for sharing
>>> changes with others.
>>>
>>> I think the benefits outweigh the issues. The initial effort of
>>> "porting" what we have over to HTML will be a bit of a chore, but I
>>> think it will be worth it.
>>>
>>> What do other people think?
>>>
>>> --
>>> 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
>>
>> _______________________________________________________
>> fluid-work mailing list - fluid-work at fluidproject.org
>> To unsubscribe, change settings or access archives,
>> see http://fluidproject.org/mailman/listinfo/fluid-work
>>
>
>
>
>
> ----------------------------------------------------------------
> This message was sent using IMP, the Internet Messaging Program.
>
> _______________________________________________________
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://fluidproject.org/mailman/listinfo/fluid-work

Allison Bloodworth
Senior User Interaction Designer
Educational Technology Services
University of California, Berkeley
(415) 377-8243
abloodworth at berkeley.edu







More information about the fluid-work mailing list