You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@directmemory.apache.org by Christoph Engelbert <no...@apache.org> on 2012/10/06 21:47:11 UTC
Lightning Documentation
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
Re: Lightning Documentation
Posted by Christoph Engelbert <no...@apache.org>.
Yeah there is a maven plugin for building documentation on doc book. We used it in our old company
Olivier Lamy <ol...@apache.org> schrieb:
>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 <ra...@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"
><si...@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
>>> <no...@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
--
Diese Nachricht wurde von meinem Android-Mobiltelefon mit K-9 Mail gesendet.
Re: Lightning Documentation
Posted by "Raffaele P. Guidi" <ra...@gmail.com>.
I'd say that - until I (or whoever is interested) will have time to spend
on setting up a docbook draft and come up with a formal vote we should
stick with the actual implementation - that is fine, in any case, and would
be perfect for the site even if we switch to docbook. You can work directly
on the directmemory site, which is in the topmost level of the repository.
Ciao,
Raffaele
On Wed, Oct 10, 2012 at 8:59 PM, Christoph Engelbert
<no...@apache.org>wrote:
> I have no favorit in docbook or xdoc, it would just good to know
> what to use when starting with the documentation and page :-)
>
> Am 09.10.2012 22:06, schrieb Simone Tripodi:
> >> Yeah since docbook uses XSLT to generate the result it's not that
> >> fast but we have a buildserver, who cares? :)
> > release managers care ;)
> >
> > http://people.apache.org/~simonetripodi/
> > http://simonetripodi.livejournal.com/
> > http://twitter.com/simonetripodi
> > http://www.99soft.org/
>
>
Re: Lightning Documentation
Posted by Christoph Engelbert <no...@apache.org>.
I have no favorit in docbook or xdoc, it would just good to know
what to use when starting with the documentation and page :-)
Am 09.10.2012 22:06, schrieb Simone Tripodi:
>> Yeah since docbook uses XSLT to generate the result it's not that
>> fast but we have a buildserver, who cares? :)
> release managers care ;)
>
> http://people.apache.org/~simonetripodi/
> http://simonetripodi.livejournal.com/
> http://twitter.com/simonetripodi
> http://www.99soft.org/
Re: Lightning Documentation
Posted by Simone Tripodi <si...@apache.org>.
> Yeah since docbook uses XSLT to generate the result it's not that
> fast but we have a buildserver, who cares? :)
release managers care ;)
http://people.apache.org/~simonetripodi/
http://simonetripodi.livejournal.com/
http://twitter.com/simonetripodi
http://www.99soft.org/
Re: Lightning Documentation
Posted by "Raffaele P. Guidi" <ra...@gmail.com>.
<< [compiling] the spring reference documentation (2.9MB+3MB of images)
takes 2.5 minutes
I forgot to mention: 2.5 mins for HTML single + HTML multi + PDF...
Ciao,
R
Il giorno 08/ott/2012 22:00, "Raffaele P. Guidi" <ra...@gmail.com>
ha scritto:
> 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 <no...@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
>> > <ra...@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" <ol...@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 <ra...@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
>> >>>>> <no...@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
>> >>>
>>
>>
>
Re: Lightning Documentation
Posted by "Raffaele P. Guidi" <ra...@gmail.com>.
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 <no...@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
> > <ra...@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" <ol...@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 <ra...@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
> >>>>> <no...@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
> >>>
>
>
Re: Lightning Documentation
Posted by Christoph Engelbert <no...@apache.org>.
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
> <ra...@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" <ol...@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 <ra...@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" <si...@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
>>>>> <no...@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
>>>
Re: Lightning Documentation
Posted by Simone Tripodi <si...@apache.org>.
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
<ra...@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" <ol...@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 <ra...@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" <si...@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
>> >> <no...@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
>>
Re: Lightning Documentation
Posted by "Raffaele P. Guidi" <ra...@gmail.com>.
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" <ol...@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 <ra...@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" <si...@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
> >> <no...@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
>
Re: Lightning Documentation
Posted by Olivier Lamy <ol...@apache.org>.
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 <ra...@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" <si...@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
>> <no...@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
Re: Lightning Documentation
Posted by "Raffaele P. Guidi" <ra...@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" <si...@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
> <no...@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
> >>>>
> >>>
> >
>
Re: Lightning Documentation
Posted by Simone Tripodi <si...@apache.org>.
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
<no...@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 <no...@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
>>>>
>>>
>
Re: Lightning Documentation
Posted by Christoph Engelbert <no...@apache.org>.
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 <no...@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
>>>
>>
Re: Lightning Documentation
Posted by "Raffaele P. Guidi" <ra...@gmail.com>.
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 <no...@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
>>
>
>
Re: Lightning Documentation
Posted by "Raffaele P. Guidi" <ra...@gmail.com>.
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 <no...@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
>