Re: Apache Syncope documentation

[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/