directmemory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Raffaele P. Guidi" <raffaele.p.gu...@gmail.com>
Subject Re: Lightning Documentation
Date Mon, 08 Oct 2012 20:00:17 GMT
And our unit and integration tests take a long, long time to run but they
are worth _every single_ millisecond. Now, our documentation has a lot of
room for improvement and, if you are worried about elapsed time, a separate
build could be triggered when only the docbook sources are modified.

In any case the velocity dbf toolkit docs (35k of document) take only 24
seconds to build on my machine while the spring reference documentation
(2.9MB+3MB of images) take 2.5 minutes - I think it is pretty affordable.

The real matter is whether we want to switch or not.

Ciao,
    R

On Mon, Oct 8, 2012 at 9:48 PM, Christoph Engelbert <noctarius@apache.org>wrote:

> Yeah since docbook uses XSLT to generate the result it's not that
> fast but we have a buildserver, who cares? :)
>
> Am 08.10.2012 16:00, schrieb Simone Tripodi:
> > I experienced docbook to publish MyBatis (formerly Apache iBATIS)
> > manuals (both pdf/html sites) and to generate them on my local machine
> > (2.3 GHz Intel Core i5, 4Gb 1333 MHz DDR3) required a laaaaaaaaarge
> > amount of time, so we migrated to Maven xdoc and reduced that time in
> > minutes.
> >
> > And yes, it was part of the build via Maven plugin.
> >
> > My 0.02 cents,
> > -Simo
> >
> > http://people.apache.org/~simonetripodi/
> > http://simonetripodi.livejournal.com/
> > http://twitter.com/simonetripodi
> > http://www.99soft.org/
> >
> >
> > On Mon, Oct 8, 2012 at 3:07 PM, Raffaele P. Guidi
> > <raffaele.p.guidi@gmail.com> wrote:
> >> I agree but docbook and his toolsuite helps organizing ideas in a
> >> consistent reference document (well, a book). That should be differently
> >> organized than the site itself. See spring or hibernate or, if you want
> to
> >> stay closer to home, apache velocity documentation. They all use docbook
> >> and have great docs (not a cohincidence IMHO).
> >>
> >> Regards,
> >>     Raffaele
> >> Il giorno 08/ott/2012 14:09, "Olivier Lamy" <olamy@apache.org> ha
> scritto:
> >>
> >>> could that be integrated in a maven site build ? Is there any maven
> >>> plugin for docbook ?
> >>> Because for javadoc maven is helpfull and well integrated for
> >>> deployment to directmemory.a.o
> >>>
> >>> And IMHO the most important is to write doc (not discussing on the
> >>> tool to do it :P )
> >>>
> >>> 2012/10/8 Raffaele P. Guidi <raffaele.p.guidi@gmail.com>:
> >>>> Yeah I know, I'm proposing a change as I'm not 100% satisfied with it
> and
> >>>> Docbook really helps in building consistent documentation.
> >>>>
> >>>> What do you think about it?
> >>>>
> >>>> Ciao,
> >>>>     R
> >>>> Il giorno 08/ott/2012 11:35, "Simone Tripodi" <
> simonetripodi@apache.org>
> >>> ha
> >>>> scritto:
> >>>>
> >>>>> Good morning,
> >>>>>
> >>>>> to publish documentation like the one on
> >>>>> http://directmemory.apache.org/ we used APT and xdoc Maven's format,
> >>>>> not docbook.
> >>>>>
> >>>>> best,
> >>>>> -Simo
> >>>>>
> >>>>> http://people.apache.org/~simonetripodi/
> >>>>> http://simonetripodi.livejournal.com/
> >>>>> http://twitter.com/simonetripodi
> >>>>> http://www.99soft.org/
> >>>>>
> >>>>>
> >>>>> On Sat, Oct 6, 2012 at 10:40 PM, Christoph Engelbert
> >>>>> <noctarius@apache.org> wrote:
> >>>>>> I worked with the docbook standard in a company before. It worked
> >>>>>> very well for documentation of an SOAP webservice and was
> >>>>>> "relatively" easy to customize in terms of layouts.
> >>>>>>
> >>>>>> So +1 from me for using docbook to create pdf and html from
the
> >>>>>> docbook standard xml.
> >>>>>>
> >>>>>> I found a really good xml editor with direct docbook support,
just
> >>>>>> need to search for it again :-)
> >>>>>>
> >>>>>> Cheers Chris
> >>>>>>
> >>>>>> Am 06.10.2012 22:36, schrieb Raffaele P. Guidi:
> >>>>>>> Yep, it was docbook. I think it brings to extremely well
done
> >>>>>>> documentation. Do you guys think that it could be worth
giving it a
> >>> try?
> >>>>>>> Ciao,
> >>>>>>>     R
> >>>>>>>
> >>>>>>> On Sat, Oct 6, 2012 at 10:24 PM, Raffaele P. Guidi <
> >>>>>>> raffaele.p.guidi@gmail.com> wrote:
> >>>>>>>
> >>>>>>>> You are welcome, thanks for getting involved :) of course
adding
> >>> docs
> >>>>> to
> >>>>>>>> the DM maven site is the preferred way even though I
wouldn't say
> >>> that
> >>>>> we
> >>>>>>>> are an excellence, when it comes to docs and probably
an easier
> way
> >>> to
> >>>>>>>> write them would help. Has anyone proposals about it?
I really
> like
> >>>>> how the
> >>>>>>>> spring framework is documented (I think it's done with
a lucene
> >>> tool,
> >>>>> don't
> >>>>>>>> remember exactly how it is called and my google karma
tonight is
> >>> low).
> >>>>>>>> Ciao,
> >>>>>>>>     R
> >>>>>>>>
> >>>>>>>>
> >>>>>>>> On Sat, Oct 6, 2012 at 9:47 PM, Christoph Engelbert
<
> >>>>> noctarius@apache.org>wrote:
> >>>>>>>>> Hey guys,
> >>>>>>>>>
> >>>>>>>>> so the account creation was successful :-) Thanks
for the given
> >>>>>>>>> trust I'm totally proud.
> >>>>>>>>>
> >>>>>>>>> The first question is how to do documentation for
Lightning? Is
> >>>>>>>>> there a preferred way to document subprojects or
do they get
> there
> >>>>>>>>> own part on the main projects page (like it seems
to be on the
> >>>>>>>>> commons projects)?
> >>>>>>>>>
> >>>>>>>>> Cheers Chris
> >>>>>>>>>
> >>>
> >>>
> >>> --
> >>> Olivier Lamy
> >>> Talend: http://coders.talend.com
> >>> http://twitter.com/olamy | http://linkedin.com/in/olamy
> >>>
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message