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/
