Agreed on first point, it was a tradeoff and it has been agreed months ago.
Second point is very subjective.
What matter in the end is that we get more doc to be written, and that
errors can be more easily fixed. Some people reported that it was
cumbersome to go edit docbook and use GIT pull request to add
documentation so we are trying something new. We don't do much mass
edit, if we have to, we can always export to docbook, use tools and
reimport.
Also this has proven to boost doc contribution or simplify doc edition,
AS7 and PortletBridge use it very successfully for instance
Now the most important is that we all write doc :)
Thomas
On 09/24/2012 11:19 PM, Julien Viet wrote:
I agree it has advantages.
there are things I don't like though and affect productivity:
- it requires to be done online in the browser and it's hard to mass edit many files
- online navigation is not great because Confluence is not a very good wiki.
On Sep 24, 2012, at 5:32 PM, Thomas Heute <theute(a)redhat.com> wrote:
> On 09/24/2012 05:11 PM, Julien Viet wrote:
>> hi,
>>
>> we are migrating to confluence but you haven't told us how it will work,
there are few things that are unclear to me:
> Pretty sure I did but not here, so I'll explain
>> - how do we contribute to the right version of the doc (3.5, 3.6, etc…)
> There is one section per version, there should be no need to push same content over 2
versions as we work on one version at a time.
> I (in the beginning at least) will duplicate content after each release.
> Best practice is to put new features in a dedicated chapter, it also helps to move
the chapter to a new version if we decide to not include the feature in the coming one.
>> - how do we extract/create a documentation for bundling with the download
> We don't. We'll link to
https://docs.jboss.org/author/display/GTNPORTAL35/Home from
http://www.jboss.org/gatein/documentation/gateinportal
>
> Note that we don't bundle docs when we do a GateIn Release.
> The project release process will be lighter as we don't need to build + push docs
anymore.
> Anyone can download a copy in PDF, HTML, EclipseHelp, and even epub by going on:
Tools > Export to...
>
> (For Products like EPP, and PLF, each one has its own method and people in charge
know what they have to do)
>
> I hope this clears things up.
>
> Thomas
>>
>> thanks
>>
>>
>> On Sep 24, 2012, at 4:55 PM, Thomas Heute <theute(a)redhat.com> wrote:
>>
>>> We are moving docs from docbook in Git to Confluence on
jboss.org.
>>>
>>> Confluence has the option to use a WYSIWYG editor or a Wiki markup
>>> editor, it instantly gives you something easy to read.
>>>
>>> I migrated user guide and reference guide for check here, it seems that
>>> it worked pretty nicely:
>>>
https://docs.jboss.org/author/display/GTNPORTAL35
>>>
>>> I want to give a few days so that people can check that the migration
>>> process is ok.
>>>
>>> It there is no objection, on Friday I will take the latest from Git and
>>> regenerate those docs and send an email here. I will also delete the
>>> docs folder from our Git repository.
>>>
>>> From that moment, any doc change will have to be done through:
>>>
https://docs.jboss.org/author/display/GTNPORTAL35
>>>
>>> Thanks,
>>> Thomas.
>>>
>>>
>>>
>>> _______________________________________________
>>> gatein-dev mailing list
>>> gatein-dev(a)lists.jboss.org
>>>
https://lists.jboss.org/mailman/listinfo/gatein-dev
>