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/