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, [email protected] 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 <[email protected]>:
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 [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
_______________________________________________________
fluid-work mailing list - [email protected]
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 - [email protected]
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
[email protected]
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
