You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@syncope.apache.org by Marco Di Sabatino Di Diodoro <ma...@tirasa.net> on 2015/09/28 13:18:10 UTC
Apache Syncope documentation
Hi all,
this morning I found this thesis [1].
I disagree about some points, but I note with regret that the
documentation of Apache Syncope is not complete and exhaustive. There
are many features that are currently not explained anywhere.
With this mail I would like to invite all of you to work together to
make Syncope more attractive and interesting.
WDYT?
Marco
[1]
https://www.theseus.fi/bitstream/handle/10024/92040/Viitanen_Samu.pdf?sequence=1
--
Dott. Marco Di Sabatino Di Diodoro
Tel. +39 3939065570
Tirasa S.r.l.
Viale D'Annunzio 267 - 65127 Pescara
Tel +39 0859116307 / FAX +39 0859111173
http://www.tirasa.net
Apache Syncope PMC Member
http://people.apache.org/~mdisabatino/
Re: Apache Syncope documentation
Posted by Francesco Chicchiriccò <il...@apache.org>.
Hi all,
I have just completed the getting started guide, and published the draft
artifacts to
http://syncope.apache.org/2.0.0-SNAPSHOT/docs/
Regards.
On 30/09/2015 15:41, Francesco Chicchiriccò wrote:
> Hi all,
> right before packing my things for Budapest, I've just pushed an
> update on the Getting Started guide, which is currently half-way: the
> missing content should be easy to adapt from some wiki pages.
>
> Please check the latest status and let me know:
>
> http://ilgrosso.github.io/syncope2/getting-started.html
> http://ilgrosso.github.io/syncope2/getting-started.pdf
>
> For those of you that are going to ApacheCon: see you there!
>
> Regards.
>
> On 29/09/2015 15:19, Francesco Chicchiriccò wrote:
>> On 29/09/2015 08:36, Marco Di Sabatino Di Diodoro wrote:
>>> Hi Francesco,
>>>
>>> Il 28/09/2015 18:22, Francesco Chicchiriccò ha scritto:
>>>> Hi,
>>>> I've opened SYNCOPE-700 to track this work.
>>>>
>>>> You can find the initial work rendered at [8] (under the "New
>>>> documentation" title), with the two guides I believe are required,
>>>> both available as HTML and PDF.
>>>>
>>>> As written below, I've added the POM configuration for generating
>>>> such documentation via AsciiDoctor, in a separate "doc" build
>>>> profile, and some initial skeleton with commit [9].
>>>>
>>>> Naturally, several things need to be improved (footer content over
>>>> all) and, mainly, the actual content is to be written.
>>>> Meanwhile, can you take a look at proposed Table Of Contents and
>>>> let me have your feedback?
>>>>
>>> It sounds good.
>>> I propose adding the following chapters:
>>>
>>> 3.6 Notifications
>>> 3.7 Audits
>>
>> Marco,
>> I have updated the TOC including the two items above and completed
>> (at least for the moment) the work on aspect, both for PDF and HTML.
>>
>> [8] was also updated.
>>
>> ...time to start writing some actual content!
>>
>> Regards.
>>
>>>> On 28/09/2015 14:06, Francesco Chicchiriccò wrote:
>>>>> On 28/09/2015 13:18, Marco Di Sabatino Di Diodoro wrote:
>>>>>> Hi all,
>>>>>>
>>>>>> this morning I found this thesis [1].
>>>>>> I disagree about some points, but I note with regret that the
>>>>>> documentation of Apache Syncope is not complete and exhaustive.
>>>>>> There are many features that are currently not explained anywhere.
>>>>>> With this mail I would like to invite all of you to work together
>>>>>> to make Syncope more attractive and interesting.
>>>>>>
>>>>>> WDYT?
>>>>>
>>>>> Marco,
>>>>> I completely agree with you.
>>>>>
>>>>> I see the great amount of inexact and / or misunderstood facts
>>>>> reported in [1] (but also in [2]) and I am getting more and more
>>>>> convinced that we absolutely need to produce a comprehensive
>>>>> documentation, to be maintained and aligned with software releases
>>>>> (as OpenJPA does [3], for example) rather than a loosely coupled
>>>>> stack of ageing wiki pages.
>>>>>
>>>>> I am ready to open an issue on JIRA for this, and I also volunteer
>>>>> for setting up the initial structure and tooling.
>>>>>
>>>>> My idea is that an adequate tool for this job needs to:
>>>>>
>>>>> 1. bundled to Maven build and (possibly) Maven site
>>>>> 2. produce at least HTML and PDF output
>>>>> 3. be diffuse enough
>>>>>
>>>>> I've seen that Docbkx [4] and the related Maven plugin [5] are
>>>>> quite stable and fulfils the requirements above .
>>>>> I'd rather go with AsciiDoc [6] and related Maven plugin [7],
>>>>> claiming to do all that and also be fast (and "à la page"
>>>>> nowadays, it seems).
>>>>>
>>>>> WDYT?
>>>>>
>>>>>> [1]
>>>>>> https://www.theseus.fi/bitstream/handle/10024/92040/Viitanen_Samu.pdf?sequence=1
>>>>> [2] https://compare.evolveum.com/details-syncope.html
>>>>> [3]
>>>>> http://openjpa.apache.org/builds/2.4.0/apache-openjpa/docs/main.html
>>>>> [4] http://docbkx-tools.sourceforge.net/
>>>>> [5]
>>>>> http://blog.javaforge.net/post/30820930927/generating-project-documentation-with-maven-docbook-docb
>>>>> [6] http://asciidoctor.org/
>>>>> [7] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
>>>> [8] http://ilgrosso.github.io/syncope2/
>>>> [9] http://git-wip-us.apache.org/repos/asf/syncope/commit/5dc51917
--
Francesco Chicchiriccò
Tirasa - Open Source Excellence
http://www.tirasa.net/
Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/
Re: Apache Syncope documentation
Posted by Francesco Chicchiriccò <il...@apache.org>.
Hi all,
right before packing my things for Budapest, I've just pushed an update
on the Getting Started guide, which is currently half-way: the missing
content should be easy to adapt from some wiki pages.
Please check the latest status and let me know:
http://ilgrosso.github.io/syncope2/getting-started.html
http://ilgrosso.github.io/syncope2/getting-started.pdf
For those of you that are going to ApacheCon: see you there!
Regards.
On 29/09/2015 15:19, Francesco Chicchiriccò wrote:
> On 29/09/2015 08:36, Marco Di Sabatino Di Diodoro wrote:
>> Hi Francesco,
>>
>> Il 28/09/2015 18:22, Francesco Chicchiriccò ha scritto:
>>> Hi,
>>> I've opened SYNCOPE-700 to track this work.
>>>
>>> You can find the initial work rendered at [8] (under the "New
>>> documentation" title), with the two guides I believe are required,
>>> both available as HTML and PDF.
>>>
>>> As written below, I've added the POM configuration for generating
>>> such documentation via AsciiDoctor, in a separate "doc" build
>>> profile, and some initial skeleton with commit [9].
>>>
>>> Naturally, several things need to be improved (footer content over
>>> all) and, mainly, the actual content is to be written.
>>> Meanwhile, can you take a look at proposed Table Of Contents and let
>>> me have your feedback?
>>>
>> It sounds good.
>> I propose adding the following chapters:
>>
>> 3.6 Notifications
>> 3.7 Audits
>
> Marco,
> I have updated the TOC including the two items above and completed (at
> least for the moment) the work on aspect, both for PDF and HTML.
>
> [8] was also updated.
>
> ...time to start writing some actual content!
>
> Regards.
>
>>> On 28/09/2015 14:06, Francesco Chicchiriccò wrote:
>>>> On 28/09/2015 13:18, Marco Di Sabatino Di Diodoro wrote:
>>>>> Hi all,
>>>>>
>>>>> this morning I found this thesis [1].
>>>>> I disagree about some points, but I note with regret that the
>>>>> documentation of Apache Syncope is not complete and exhaustive.
>>>>> There are many features that are currently not explained anywhere.
>>>>> With this mail I would like to invite all of you to work together
>>>>> to make Syncope more attractive and interesting.
>>>>>
>>>>> WDYT?
>>>>
>>>> Marco,
>>>> I completely agree with you.
>>>>
>>>> I see the great amount of inexact and / or misunderstood facts
>>>> reported in [1] (but also in [2]) and I am getting more and more
>>>> convinced that we absolutely need to produce a comprehensive
>>>> documentation, to be maintained and aligned with software releases
>>>> (as OpenJPA does [3], for example) rather than a loosely coupled
>>>> stack of ageing wiki pages.
>>>>
>>>> I am ready to open an issue on JIRA for this, and I also volunteer
>>>> for setting up the initial structure and tooling.
>>>>
>>>> My idea is that an adequate tool for this job needs to:
>>>>
>>>> 1. bundled to Maven build and (possibly) Maven site
>>>> 2. produce at least HTML and PDF output
>>>> 3. be diffuse enough
>>>>
>>>> I've seen that Docbkx [4] and the related Maven plugin [5] are
>>>> quite stable and fulfils the requirements above .
>>>> I'd rather go with AsciiDoc [6] and related Maven plugin [7],
>>>> claiming to do all that and also be fast (and "à la page" nowadays,
>>>> it seems).
>>>>
>>>> WDYT?
>>>>
>>>>> [1]
>>>>> https://www.theseus.fi/bitstream/handle/10024/92040/Viitanen_Samu.pdf?sequence=1
>>>> [2] https://compare.evolveum.com/details-syncope.html
>>>> [3]
>>>> http://openjpa.apache.org/builds/2.4.0/apache-openjpa/docs/main.html
>>>> [4] http://docbkx-tools.sourceforge.net/
>>>> [5]
>>>> http://blog.javaforge.net/post/30820930927/generating-project-documentation-with-maven-docbook-docb
>>>> [6] http://asciidoctor.org/
>>>> [7] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
>>> [8] http://ilgrosso.github.io/syncope2/
>>> [9] http://git-wip-us.apache.org/repos/asf/syncope/commit/5dc51917
--
Francesco Chicchiriccò
Tirasa - Open Source Excellence
http://www.tirasa.net/
Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/
Re: Apache Syncope documentation
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 29/09/2015 08:36, Marco Di Sabatino Di Diodoro wrote:
> Hi Francesco,
>
> Il 28/09/2015 18:22, Francesco Chicchiriccò ha scritto:
>> Hi,
>> I've opened SYNCOPE-700 to track this work.
>>
>> You can find the initial work rendered at [8] (under the "New
>> documentation" title), with the two guides I believe are required,
>> both available as HTML and PDF.
>>
>> As written below, I've added the POM configuration for generating
>> such documentation via AsciiDoctor, in a separate "doc" build
>> profile, and some initial skeleton with commit [9].
>>
>> Naturally, several things need to be improved (footer content over
>> all) and, mainly, the actual content is to be written.
>> Meanwhile, can you take a look at proposed Table Of Contents and let
>> me have your feedback?
>>
> It sounds good.
> I propose adding the following chapters:
>
> 3.6 Notifications
> 3.7 Audits
Marco,
I have updated the TOC including the two items above and completed (at
least for the moment) the work on aspect, both for PDF and HTML.
[8] was also updated.
...time to start writing some actual content!
Regards.
>> On 28/09/2015 14:06, Francesco Chicchiriccò wrote:
>>> On 28/09/2015 13:18, Marco Di Sabatino Di Diodoro wrote:
>>>> Hi all,
>>>>
>>>> this morning I found this thesis [1].
>>>> I disagree about some points, but I note with regret that the
>>>> documentation of Apache Syncope is not complete and exhaustive.
>>>> There are many features that are currently not explained anywhere.
>>>> With this mail I would like to invite all of you to work together
>>>> to make Syncope more attractive and interesting.
>>>>
>>>> WDYT?
>>>
>>> Marco,
>>> I completely agree with you.
>>>
>>> I see the great amount of inexact and / or misunderstood facts
>>> reported in [1] (but also in [2]) and I am getting more and more
>>> convinced that we absolutely need to produce a comprehensive
>>> documentation, to be maintained and aligned with software releases
>>> (as OpenJPA does [3], for example) rather than a loosely coupled
>>> stack of ageing wiki pages.
>>>
>>> I am ready to open an issue on JIRA for this, and I also volunteer
>>> for setting up the initial structure and tooling.
>>>
>>> My idea is that an adequate tool for this job needs to:
>>>
>>> 1. bundled to Maven build and (possibly) Maven site
>>> 2. produce at least HTML and PDF output
>>> 3. be diffuse enough
>>>
>>> I've seen that Docbkx [4] and the related Maven plugin [5] are quite
>>> stable and fulfils the requirements above .
>>> I'd rather go with AsciiDoc [6] and related Maven plugin [7],
>>> claiming to do all that and also be fast (and "à la page" nowadays,
>>> it seems).
>>>
>>> WDYT?
>>>
>>>> [1]
>>>> https://www.theseus.fi/bitstream/handle/10024/92040/Viitanen_Samu.pdf?sequence=1
>>> [2] https://compare.evolveum.com/details-syncope.html
>>> [3]
>>> http://openjpa.apache.org/builds/2.4.0/apache-openjpa/docs/main.html
>>> [4] http://docbkx-tools.sourceforge.net/
>>> [5]
>>> http://blog.javaforge.net/post/30820930927/generating-project-documentation-with-maven-docbook-docb
>>> [6] http://asciidoctor.org/
>>> [7] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
>> [8] http://ilgrosso.github.io/syncope2/
>> [9] http://git-wip-us.apache.org/repos/asf/syncope/commit/5dc51917
--
Francesco Chicchiriccò
Tirasa - Open Source Excellence
http://www.tirasa.net/
Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/
Re: Apache Syncope documentation
Posted by Marco Di Sabatino Di Diodoro <ma...@tirasa.net>.
Hi Francesco,
Il 28/09/2015 18:22, Francesco Chicchiriccò ha scritto:
> Hi,
> I've opened SYNCOPE-700 to track this work.
>
> You can find the initial work rendered at [8] (under the "New
> documentation" title), with the two guides I believe are required,
> both available as HTML and PDF.
>
> As written below, I've added the POM configuration for generating such
> documentation via AsciiDoctor, in a separate "doc" build profile, and
> some initial skeleton with commit [9].
>
> Naturally, several things need to be improved (footer content over
> all) and, mainly, the actual content is to be written.
> Meanwhile, can you take a look at proposed Table Of Contents and let
> me have your feedback?
>
It sounds good.
I propose adding the following chapters:
3.6 Notifications
3.7 Audits
Regards
Marco
> Regards.
>
> On 28/09/2015 14:06, Francesco Chicchiriccò wrote:
>> On 28/09/2015 13:18, Marco Di Sabatino Di Diodoro wrote:
>>> Hi all,
>>>
>>> this morning I found this thesis [1].
>>> I disagree about some points, but I note with regret that the
>>> documentation of Apache Syncope is not complete and exhaustive.
>>> There are many features that are currently not explained anywhere.
>>> With this mail I would like to invite all of you to work together to
>>> make Syncope more attractive and interesting.
>>>
>>> WDYT?
>>
>> Marco,
>> I completely agree with you.
>>
>> I see the great amount of inexact and / or misunderstood facts
>> reported in [1] (but also in [2]) and I am getting more and more
>> convinced that we absolutely need to produce a comprehensive
>> documentation, to be maintained and aligned with software releases
>> (as OpenJPA does [3], for example) rather than a loosely coupled
>> stack of ageing wiki pages.
>>
>> I am ready to open an issue on JIRA for this, and I also volunteer
>> for setting up the initial structure and tooling.
>>
>> My idea is that an adequate tool for this job needs to:
>>
>> 1. bundled to Maven build and (possibly) Maven site
>> 2. produce at least HTML and PDF output
>> 3. be diffuse enough
>>
>> I've seen that Docbkx [4] and the related Maven plugin [5] are quite
>> stable and fulfils the requirements above .
>> I'd rather go with AsciiDoc [6] and related Maven plugin [7],
>> claiming to do all that and also be fast (and "à la page" nowadays,
>> it seems).
>>
>> WDYT?
>>
>>> [1]
>>> https://www.theseus.fi/bitstream/handle/10024/92040/Viitanen_Samu.pdf?sequence=1
>> [2] https://compare.evolveum.com/details-syncope.html
>> [3] http://openjpa.apache.org/builds/2.4.0/apache-openjpa/docs/main.html
>> [4] http://docbkx-tools.sourceforge.net/
>> [5]
>> http://blog.javaforge.net/post/30820930927/generating-project-documentation-with-maven-docbook-docb
>> [6] http://asciidoctor.org/
>> [7] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
> [8] http://ilgrosso.github.io/syncope2/
> [9] http://git-wip-us.apache.org/repos/asf/syncope/commit/5dc51917
>
--
Dott. Marco Di Sabatino Di Diodoro
Tel. +39 3939065570
Tirasa S.r.l.
Viale D'Annunzio 267 - 65127 Pescara
Tel +39 0859116307 / FAX +39 0859111173
http://www.tirasa.net
Apache Syncope PMC Member
http://people.apache.org/~mdisabatino/
Re: Apache Syncope documentation
Posted by Francesco Chicchiriccò <il...@apache.org>.
Hi,
I've opened SYNCOPE-700 to track this work.
You can find the initial work rendered at [8] (under the "New
documentation" title), with the two guides I believe are required, both
available as HTML and PDF.
As written below, I've added the POM configuration for generating such
documentation via AsciiDoctor, in a separate "doc" build profile, and
some initial skeleton with commit [9].
Naturally, several things need to be improved (footer content over all)
and, mainly, the actual content is to be written.
Meanwhile, can you take a look at proposed Table Of Contents and let me
have your feedback?
Regards.
On 28/09/2015 14:06, Francesco Chicchiriccò wrote:
> On 28/09/2015 13:18, Marco Di Sabatino Di Diodoro wrote:
>> Hi all,
>>
>> this morning I found this thesis [1].
>> I disagree about some points, but I note with regret that the
>> documentation of Apache Syncope is not complete and exhaustive. There
>> are many features that are currently not explained anywhere.
>> With this mail I would like to invite all of you to work together to
>> make Syncope more attractive and interesting.
>>
>> WDYT?
>
> Marco,
> I completely agree with you.
>
> I see the great amount of inexact and / or misunderstood facts
> reported in [1] (but also in [2]) and I am getting more and more
> convinced that we absolutely need to produce a comprehensive
> documentation, to be maintained and aligned with software releases (as
> OpenJPA does [3], for example) rather than a loosely coupled stack of
> ageing wiki pages.
>
> I am ready to open an issue on JIRA for this, and I also volunteer for
> setting up the initial structure and tooling.
>
> My idea is that an adequate tool for this job needs to:
>
> 1. bundled to Maven build and (possibly) Maven site
> 2. produce at least HTML and PDF output
> 3. be diffuse enough
>
> I've seen that Docbkx [4] and the related Maven plugin [5] are quite
> stable and fulfils the requirements above .
> I'd rather go with AsciiDoc [6] and related Maven plugin [7], claiming
> to do all that and also be fast (and "à la page" nowadays, it seems).
>
> WDYT?
>
>> [1]
>> https://www.theseus.fi/bitstream/handle/10024/92040/Viitanen_Samu.pdf?sequence=1
> [2] https://compare.evolveum.com/details-syncope.html
> [3] http://openjpa.apache.org/builds/2.4.0/apache-openjpa/docs/main.html
> [4] http://docbkx-tools.sourceforge.net/
> [5]
> http://blog.javaforge.net/post/30820930927/generating-project-documentation-with-maven-docbook-docb
> [6] http://asciidoctor.org/
> [7] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
[8] http://ilgrosso.github.io/syncope2/
[9] http://git-wip-us.apache.org/repos/asf/syncope/commit/5dc51917
--
Francesco Chicchiriccò
Tirasa - Open Source Excellence
http://www.tirasa.net/
Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/
Re: Apache Syncope documentation
Posted by Marco Di Sabatino Di Diodoro <ma...@tirasa.net>.
Il 28/09/2015 14:06, Francesco Chicchiriccò ha scritto:
> On 28/09/2015 13:18, Marco Di Sabatino Di Diodoro wrote:
>> Hi all,
>>
>> this morning I found this thesis [1].
>> I disagree about some points, but I note with regret that the
>> documentation of Apache Syncope is not complete and exhaustive. There
>> are many features that are currently not explained anywhere.
>> With this mail I would like to invite all of you to work together to
>> make Syncope more attractive and interesting.
>>
>> WDYT?
>
> Marco,
> I completely agree with you.
>
> I see the great amount of inexact and / or misunderstood facts
> reported in [1] (but also in [2]) and I am getting more and more
> convinced that we absolutely need to produce a comprehensive
> documentation, to be maintained and aligned with software releases (as
> OpenJPA does [3], for example) rather than a loosely coupled stack of
> ageing wiki pages.
>
> I am ready to open an issue on JIRA for this, and I also volunteer for
> setting up the initial structure and tooling.
>
> My idea is that an adequate tool for this job needs to:
>
> 1. bundled to Maven build and (possibly) Maven site
> 2. produce at least HTML and PDF output
> 3. be diffuse enough
>
> I've seen that Docbkx [4] and the related Maven plugin [5] are quite
> stable and fulfils the requirements above .
> I'd rather go with [6] and related Maven plugin [7], claiming to
> do all that and also be fast (and "à la page" nowadays, it seems).
>
> WDYT?
Great! I agree with you.
M
>
>> [1]
>> https://www.theseus.fi/bitstream/handle/10024/92040/Viitanen_Samu.pdf?sequence=1
> [2] https://compare.evolveum.com/details-syncope.html
> [3] http://openjpa.apache.org/builds/2.4.0/apache-openjpa/docs/main.html
> [4] http://docbkx-tools.sourceforge.net/
> [5]
> http://blog.javaforge.net/post/30820930927/generating-project-documentation-with-maven-docbook-docb
> [6] http://asciidoctor.org/
> [7] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
>
--
Dott. Marco Di Sabatino Di Diodoro
Tel. +39 3939065570
Tirasa S.r.l.
Viale D'Annunzio 267 - 65127 Pescara
Tel +39 0859116307 / FAX +39 0859111173
http://www.tirasa.net
Apache Syncope PMC Member
http://people.apache.org/~mdisabatino/
Re: Apache Syncope documentation
Posted by Andrea Patricelli <an...@tirasa.net>.
----- Messaggio originale -----
Da: "andrea patricelli" <an...@tirasa.net>
A: dev@syncope.apache.org
Inviato: Lunedì, 28 settembre 2015 14:30:25
Oggetto: Re: Apache Syncope documentation
Il 28/09/2015 14:06, Francesco Chicchiriccò ha scritto:
> On 28/09/2015 13:18, Marco Di Sabatino Di Diodoro wrote:
>> Hi all,
>>
>> this morning I found this thesis [1].
>> I disagree about some points, but I note with regret that the
>> documentation of Apache Syncope is not complete and exhaustive. There
>> are many features that are currently not explained anywhere.
>> With this mail I would like to invite all of you to work together to
>> make Syncope more attractive and interesting.
>>
>> WDYT?
>
> Marco,
> I completely agree with you.
>
> I see the great amount of inexact and / or misunderstood facts
> reported in [1] (but also in [2]) and I am getting more and more
> convinced that we absolutely need to produce a comprehensive
> documentation, to be maintained and aligned with software releases (as
> OpenJPA does [3], for example) rather than a loosely coupled stack of
> ageing wiki pages.
>
> I am ready to open an issue on JIRA for this, and I also volunteer for
> setting up the initial structure and tooling.
>
> My idea is that an adequate tool for this job needs to:
>
> 1. bundled to Maven build and (possibly) Maven site
> 2. produce at least HTML and PDF output
> 3. be diffuse enough
>
> I've seen that Docbkx [4] and the related Maven plugin [5] are quite
> stable and fulfils the requirements above .
> I'd rather go with AsciiDoc [6] and related Maven plugin [7], claiming
> to do all that and also be fast (and "à la page" nowadays, it seems).
>
> WDYT?
>
+ 1 to Francesco's proposal, and also for Marco's that rised this
important problem. You have all my support to improve and diffuse
correct and complete infos.
>> [1]
>> https://www.theseus.fi/bitstream/handle/10024/92040/Viitanen_Samu.pdf?sequence=1
> [2] https://compare.evolveum.com/details-syncope.html
> [3] http://openjpa.apache.org/builds/2.4.0/apache-openjpa/docs/main.html
> [4] http://docbkx-tools.sourceforge.net/
> [5]
> http://blog.javaforge.net/post/30820930927/generating-project-documentation-with-maven-docbook-docb
> [6] http://asciidoctor.org/
> [7] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
>
Best regards,
Andrea
--
Dott. Andrea Patricelli
Tel +393204524292
Junior Engineer @ Tirasa S.r.l.
Viale D'Annunzio 267 - 65127 Pescara
Tel +390859116307 / FAX +39 0859111173
http://www.tirasa.net
Re: Apache Syncope documentation
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 28/09/2015 13:18, Marco Di Sabatino Di Diodoro wrote:
> Hi all,
>
> this morning I found this thesis [1].
> I disagree about some points, but I note with regret that the
> documentation of Apache Syncope is not complete and exhaustive. There
> are many features that are currently not explained anywhere.
> With this mail I would like to invite all of you to work together to
> make Syncope more attractive and interesting.
>
> WDYT?
Marco,
I completely agree with you.
I see the great amount of inexact and / or misunderstood facts reported
in [1] (but also in [2]) and I am getting more and more convinced that
we absolutely need to produce a comprehensive documentation, to be
maintained and aligned with software releases (as OpenJPA does [3], for
example) rather than a loosely coupled stack of ageing wiki pages.
I am ready to open an issue on JIRA for this, and I also volunteer for
setting up the initial structure and tooling.
My idea is that an adequate tool for this job needs to:
1. bundled to Maven build and (possibly) Maven site
2. produce at least HTML and PDF output
3. be diffuse enough
I've seen that Docbkx [4] and the related Maven plugin [5] are quite
stable and fulfils the requirements above .
I'd rather go with AsciiDoc [6] and related Maven plugin [7], claiming
to do all that and also be fast (and "à la page" nowadays, it seems).
WDYT?
> [1]
> https://www.theseus.fi/bitstream/handle/10024/92040/Viitanen_Samu.pdf?sequence=1
[2] https://compare.evolveum.com/details-syncope.html
[3] http://openjpa.apache.org/builds/2.4.0/apache-openjpa/docs/main.html
[4] http://docbkx-tools.sourceforge.net/
[5]
http://blog.javaforge.net/post/30820930927/generating-project-documentation-with-maven-docbook-docb
[6] http://asciidoctor.org/
[7] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
--
Francesco Chicchiriccò
Tirasa - Open Source Excellence
http://www.tirasa.net/
Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/