What should we do about API documentation?

antranig at caret.cam.ac.uk antranig at caret.cam.ac.uk
Sat Jan 17 00:36:51 UTC 2009


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.




More information about the fluid-work mailing list