----- Messaggio originale ----- Da: "andrea patricelli" <andrea.patrice...@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
