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/