RE: AWare

We've been using docbook on AspectJ for the last 3 years.  When we were
deciding on the switch from HTML my programmer side was happy, but my
practical side worried.  Overall it has been more of a negative than a
positive for exactly the reasons that you state.  Now that we don't have a
dedicated documentation person the bar for people contributing to and
updating the docs is too high.  A related reason is that the HTML authoring
tools that people know and love don't work for it.  Finally, converting HTML
to PDF isn't all that bad, and for AspectJ all we really need is HTML and
PDF.

Mik

--
http://kerstens.org/mik

> -----Original Message-----
> From: aspectwerkz-devel-admin-81qHHgoATdGxIXFVlbCvtR2eb7JE58TQ@public.gmane.org [mailto:aspectwerkz-
> [email protected]] On Behalf Of Jonas Boner
> Sent: Wednesday, April 28, 2004 12:14 AM
> To: Jérôme BERNARD
> Cc: aspectwerkz-devel-81qHHgoATdGxIXFVlbCvtR2eb7JE58TQ@public.gmane.org
> Subject: RE: [aspectwerkz-devel] AWare
> 
> I agree that docbook is generally a better format to write documentation
> in, but don't you think that it will be easier to get people to, first
> contribute and second write good docs, if we keep it as simple as
possible.
> The tools should not stand in the way. Confluence seems to be working fine
> for Pico.
> We could set up rights on how gets to modify what etc.
> 
> /jonas
> 
> -----Original Message-----
> From:	Jérôme BERNARD [mailto:[email protected]]
> Sent:	Wed 4/28/2004 7:46 AM
> To:	Jonas Boner
> Cc:	aspectwerkz-devel-81qHHgoATdGxIXFVlbCvtR2eb7JE58TQ@public.gmane.org
> Subject:	Re: [aspectwerkz-devel] AWare
> Jonas Boner wrote:
> 
> >What about the namespace for the classes? What do you think is best to
> do?
> >
> >    Can we wait with this a couple of days?
> >
> >
> Sure, it won't be hard to refactor this with IDEA :-)
> 
> >I'll keep working on the unit-tests so that they cover as much code as
> >possible.
> >
> >    Great. This should be a criteria for check-in.
> >
> >
> I have reach 70% of code coverage which seems quite good when looking at
> the results from Clover.
> 
> >Next, I will probably start to write some doc somewhere on how to use
> >it. BTW what would be the best format for it? xdoc? sdocbook?
> >
> >    AspectWerkz uses xdoc. Personally I am fond of docbook, but that is
> more complex. We need a format that can be easily used by any user. I
> guess xdoc is better. Another alt. would be the confluence wiki. What do
> you think?
> >
> >
> xdoc is quite easy but I find it a bit more restrictive on customization
> than docbook. moreover transformation is not done using XSLT but Jelly
> scripts which my be an issue later on if we need to do something
> "advanced".
> confluence would be the easier step for me as my website is run with
> SnipSnap: I suppose there is a simply way to migrate the content.
> I think we need to think in terms of deliverables for the doc: HTML
> version? PDF version? or a wiki (à la Hibernate)?
> My preference would probably be for docbook too, but I do not know if
> many developers know docbook. BTW there is probably some good WYSIWYG
> docbook editors?
> 
> Jérôme.
> 
> 
> 
> _______________________________________________
> aspectwerkz-devel mailing list
> aspectwerkz-devel-81qHHgoATdGxIXFVlbCvtR2eb7JE58TQ@public.gmane.org
> http://lists.codehaus.org/mailman/listinfo/aspectwerkz-devel