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

From: "Thomas Heute" <theute(a)redhat.com&gt; To: "Julien Viet" <julien(a)julienviet.com&gt; Cc: "gatein-dev" <gatein-dev(a)lists.jboss.org&gt;, "Jared Morgan" <jmorgan(a)redhat.com&gt; Sent: Tuesday, September 25, 2012 1:32:52 AM Subject: Re: [gatein-dev] Doc migration preview 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&gt; > 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

From: "Julien Viet" <julien(a)julienviet.com&gt; To: "Jared Morgan" <jmorgan(a)redhat.com&gt; Cc: "gatein-dev" <gatein-dev(a)lists.jboss.org&gt;, "Thomas Heute" <theute(a)redhat.com&gt; Sent: Tuesday, September 25, 2012 7:15:00 AM Subject: Re: [gatein-dev] Doc migration preview so if we improve a section that is copied multiple times in 3.5 / 3.6 / … there is something to automatically synchronize the change among the different version of the same page ? On Sep 24, 2012, at 10:52 PM, Jared Morgan <jmorgan(a)redhat.com&gt; wrote: > Another obvious advantage to not bundling docs in a release is > asynchronous updates to the docs. > > The docs on GTNPORTAL35 can be continuously improved if required, > with minor tweaks to the guides made mid-way through a release > cycle if necessary. > > Jared Morgan > EPP Docs Lead | PressGang Lead | RHCSA (120-008-248) > Red Hat Asia Pacific > 1/193 North Quay > BRISBANE QLD 4000 > > P: +61 7 3514 8242 > M: +61 413 005 479 > > Too brief? Here's why! http://emailcharter.org > > ----- Original Message ----- >> From: "Thomas Heute" <theute(a)redhat.com&gt; >> To: "Julien Viet" <julien(a)julienviet.com&gt; >> Cc: "gatein-dev" <gatein-dev(a)lists.jboss.org&gt;, "Jared Morgan" >> <jmorgan(a)redhat.com&gt; >> Sent: Tuesday, September 25, 2012 1:32:52 AM >> Subject: Re: [gatein-dev] Doc migration preview >> >> 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&gt; >>> 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 >> >>

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&gt; 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&gt; 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 >

On 24 sept. 2012, at 16:55, Thomas Heute <theute(a)redhat.com&gt; 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. Seems like internal links between sections were not properly ported…

Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm

On 24 sept. 2012, at 17:38, Thomas Heute <theute(a)redhat.com&gt; wrote: > On 09/24/2012 05:14 PM, Christophe Laprun wrote: >> On 24 sept. 2012, at 16:55, Thomas Heute <theute(a)redhat.com&gt; 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. >> Seems like internal links between sections were not properly ported… > I couldn't find one (or maybe they are gone ?) do you have a link where you see that issue ? WSRP for example: https://docs.jboss.org/author/display/GTNPORTAL35/Web+Services+for+Remote... The broken links show up in red with the name of the section id instead of being replaced by the title of the section and a link to it as it previously was the case.

Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm

Hi, I noticed some change. Links on http://www.jboss.org/gatein/documentation/gateinportal are broken for Administration guide and Developer guide. It points to https://docs.jboss.org/author/display/GTNPORTAL/Developer+Guide but should be https://docs.jboss.org/author/display/GTNPORTAL35/Developer+Guide Honza ----- Original Message ----- > From: "Thomas Heute" <theute(a)redhat.com&gt; > To: "gatein-dev" <gatein-dev(a)lists.jboss.org&gt; > Cc: "Jared Morgan" <jmorgan(a)redhat.com&gt; > Sent: Monday, September 24, 2012 4:55:06 PM > Subject: [gatein-dev] Doc migration preview > > > 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 >

There were 2 questions/comments: - Can we keep semantic of docbook ? Answer is no. The Wysiwyg and WIKI markup have smaller scope for semantic (which isn't bad as we tend to use different semantic in docbook for the samething such as programlisting vs code). There is an authoring guide here that I would recommend to follow even though, it's quite natural: https://docs.jboss.org/author/display/AUTHGUIDE/Markup+Guide - Cross-reference links (to sections) are broken. Indeed there is an issue here, it works fine when it references a chapter but not a section. I mentioned the issue but I prefer not to wait on resolution. There are 52 links like that that are broken, I'm still checking if I can fix them prior to the import, otherwise I will fix some when reviewing the doc. I won't migrate today because of the second issue, so for now, please continue with docbook in GIT. Thanks, Thomas. On 09/24/2012 04:55 PM, Thomas Heute 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 > _______________________________________________ gatein-dev mailing list gatein-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/gatein-dev