The REST server comes with a small web app containing an HTML with the documentation in https://docs.jboss.org/author/display/ISPN/Accessing+data+in+Infinispan+v... Keeping the documentation in both places is a waster of energy and it can quickly get out of sync. I proposed the HTML gets changed to point to https://docs.jboss.org/author/display/ISPN/Accessing+data+in+Infinispan+v... and keep the docu up to date there. Thoughts? -- Galder Zamarreño Sr. Software Engineer Infinispan, JBoss Cache _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev

I believe confluence can deal with different versions of the same document (I vaguely remember this from a conversion w/ Mark N but can't find an email ref) Besides, maintaining documents in Confluence is easier than manually editing HTML On Jun 29, 2011, at 2:35 PM, Emmanuel Bernard wrote: > How do you cope with version change. The nicety with embedded doc is that it's the one for the software version you use. > > On 29 juin 2011, at 14:22, Galder Zamarreño<galder(a)redhat.com> wrote: > >> The REST server comes with a small web app containing an HTML with the documentation in https://docs.jboss.org/author/display/ISPN/Accessing+data+in+Infinispan+v... >> >> Keeping the documentation in both places is a waster of energy and it can quickly get out of sync. >> >> I proposed the HTML gets changed to point to https://docs.jboss.org/author/display/ISPN/Accessing+data+in+Infinispan+v... and keep the docu up to date there. >> >> Thoughts? >> -- >> Galder Zamarreño >> Sr. Software Engineer >> Infinispan, JBoss Cache >> >> >> _______________________________________________ >> infinispan-dev mailing list >> infinispan-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > _______________________________________________ > infinispan-dev mailing list > infinispan-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/infinispan-dev -- Galder Zamarreño Sr. Software Engineer Infinispan, JBoss Cache _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev

The approach the JBoss.org team have taken is that Confluence is just for editing the "HEAD" of the docs. If we want to version docs, we need to export a version to e.g. PDF or Docbook and tag that as part of a release. We are planning not to export docs, but instead take a slightly different approach (we'll see how it works out). * Use "@since" style annotation for the doc to indicate that the docs are only relevant since a particular version. Probably we would use a {note} admonition for this. We'll need to mark docs as out of date as well. * We'll build a doc for each major version, using includes to pull in each doc which is relevant. I'll write this up for the doc writing guide when I get that doc up. (Got delayed by f2f meeting and webinars ;-). On 29 Jun 2011, at 13:46, Galder Zamarreño wrote: > I believe confluence can deal with different versions of the same document (I vaguely remember this from a conversion w/ Mark N but can't find an email ref) > > Besides, maintaining documents in Confluence is easier than manually editing HTML > > On Jun 29, 2011, at 2:35 PM, Emmanuel Bernard wrote: > >> How do you cope with version change. The nicety with embedded doc is that it's the one for the software version you use. >> >> On 29 juin 2011, at 14:22, Galder Zamarreño <galder(a)redhat.com&gt; wrote: >> >>> The REST server comes with a small web app containing an HTML with the documentation in https://docs.jboss.org/author/display/ISPN/Accessing+data+in+Infinispan+v... >>> >>> Keeping the documentation in both places is a waster of energy and it can quickly get out of sync. >>> >>> I proposed the HTML gets changed to point to https://docs.jboss.org/author/display/ISPN/Accessing+data+in+Infinispan+v... and keep the docu up to date there. >>> >>> Thoughts? >>> -- >>> Galder Zamarreño >>> Sr. Software Engineer >>> Infinispan, JBoss Cache >>> >>> >>> _______________________________________________ >>> infinispan-dev mailing list >>> infinispan-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/infinispan-dev >> >> _______________________________________________ >> infinispan-dev mailing list >> infinispan-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > > -- > Galder Zamarreño > Sr. Software Engineer > Infinispan, JBoss Cache > > > _______________________________________________ > infinispan-dev mailing list > infinispan-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/infinispan-dev _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev

I forgot to answer that bit ;-) Yes, I think we should merge it with the main doc. Include a pointer (i.e. splash page) where the doc was with a link. On 4 Jul 2011, at 07:44, Galder Zamarreño wrote: > What's the rest thinking about this? > > Are we all fine with removing the contents of the html and pointing to the docu in docs.jboss.org? > > On Jun 30, 2011, at 9:14 AM, Pete Muir wrote: > >> The approach the JBoss.org team have taken is that Confluence is just for editing the "HEAD" of the docs. If we want to version docs, we need to export a version to e.g. PDF or Docbook and tag that as part of a release. >> >> We are planning not to export docs, but instead take a slightly different approach (we'll see how it works out). >> >> * Use "@since" style annotation for the doc to indicate that the docs are only relevant since a particular version. Probably we would use a {note} admonition for this. We'll need to mark docs as out of date as well. >> * We'll build a doc for each major version, using includes to pull in each doc which is relevant. >> >> I'll write this up for the doc writing guide when I get that doc up. (Got delayed by f2f meeting and webinars ;-). >> >> On 29 Jun 2011, at 13:46, Galder Zamarreño wrote: >> >>> I believe confluence can deal with different versions of the same document (I vaguely remember this from a conversion w/ Mark N but can't find an email ref) >>> >>> Besides, maintaining documents in Confluence is easier than manually editing HTML >>> >>> On Jun 29, 2011, at 2:35 PM, Emmanuel Bernard wrote: >>> >>>> How do you cope with version change. The nicety with embedded doc is that it's the one for the software version you use. >>>> >>>> On 29 juin 2011, at 14:22, Galder Zamarreño <galder(a)redhat.com&gt; wrote: >>>> >>>>> The REST server comes with a small web app containing an HTML with the documentation in https://docs.jboss.org/author/display/ISPN/Accessing+data+in+Infinispan+v... >>>>> >>>>> Keeping the documentation in both places is a waster of energy and it can quickly get out of sync. >>>>> >>>>> I proposed the HTML gets changed to point to https://docs.jboss.org/author/display/ISPN/Accessing+data+in+Infinispan+v... and keep the docu up to date there. >>>>> >>>>> Thoughts? >>>>> -- >>>>> Galder Zamarreño >>>>> Sr. Software Engineer >>>>> Infinispan, JBoss Cache >>>>> >>>>> >>>>> _______________________________________________ >>>>> infinispan-dev mailing list >>>>> infinispan-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev >>>> >>>> _______________________________________________ >>>> infinispan-dev mailing list >>>> infinispan-dev(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev >>> >>> -- >>> Galder Zamarreño >>> Sr. Software Engineer >>> Infinispan, JBoss Cache >>> >>> >>> _______________________________________________ >>> infinispan-dev mailing list >>> infinispan-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/infinispan-dev >> >> >> _______________________________________________ >> infinispan-dev mailing list >> infinispan-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > > -- > Galder Zamarreño > Sr. Software Engineer > Infinispan, JBoss Cache > > > _______________________________________________ > infinispan-dev mailing list > infinispan-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/infinispan-dev _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev