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/