[infinispan-dev] RESTful API docu

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

[infinispan-dev] RESTful API docu

Galder Zamarreno
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+via+RESTful+interface

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+via+RESTful+interface and keep the docu up to date there.

Thoughts?
--
Galder Zamarreño
Sr. Software Engineer
Infinispan, JBoss Cache


_______________________________________________
infinispan-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/infinispan-dev
Reply | Threaded
Open this post in threaded view
|

Re: [infinispan-dev] RESTful API docu

Emmanuel Bernard
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 <[hidden email]> 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+via+RESTful+interface
>
> 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+via+RESTful+interface and keep the docu up to date there.
>
> Thoughts?
> --
> Galder Zamarreño
> Sr. Software Engineer
> Infinispan, JBoss Cache
>
>
> _______________________________________________
> infinispan-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/infinispan-dev

_______________________________________________
infinispan-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/infinispan-dev
Reply | Threaded
Open this post in threaded view
|

Re: [infinispan-dev] RESTful API docu

Galder Zamarreno
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 <[hidden email]> 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+via+RESTful+interface
>>
>> 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+via+RESTful+interface and keep the docu up to date there.
>>
>> Thoughts?
>> --
>> Galder Zamarreño
>> Sr. Software Engineer
>> Infinispan, JBoss Cache
>>
>>
>> _______________________________________________
>> infinispan-dev mailing list
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
> _______________________________________________
> infinispan-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/infinispan-dev

--
Galder Zamarreño
Sr. Software Engineer
Infinispan, JBoss Cache


_______________________________________________
infinispan-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/infinispan-dev
Reply | Threaded
Open this post in threaded view
|

Re: [infinispan-dev] RESTful API docu

Michal Linhard
And that would have to be solved anyway, not just for REST API.
I guess each major version branch should have its own documentation tree.

Anyway +1 to keeping only one REST API doc and avoiding duplication.

m.
On 06/29/2011 02:46 PM, 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<[hidden email]>  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+via+RESTful+interface
>>>
>>> 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+via+RESTful+interface and keep the docu up to date there.
>>>
>>> Thoughts?
>>> --
>>> Galder Zamarreño
>>> Sr. Software Engineer
>>> Infinispan, JBoss Cache
>>>
>>>
>>> _______________________________________________
>>> infinispan-dev mailing list
>>> [hidden email]
>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>> _______________________________________________
>> infinispan-dev mailing list
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
> --
> Galder Zamarreño
> Sr. Software Engineer
> Infinispan, JBoss Cache
>
>
> _______________________________________________
> infinispan-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/infinispan-dev


--
Michal Linhard
Quality Assurance Engineer

Red Hat Czech s.r.o.
Purkynova 99 612 45 Brno, Czech Republic
phone: +420 532 294 320 ext. 62320
mobile: +420 728 626 363

_______________________________________________
infinispan-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/infinispan-dev
Reply | Threaded
Open this post in threaded view
|

Re: [infinispan-dev] RESTful API docu

Pete Muir
In reply to this post by Galder Zamarreno
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 <[hidden email]> 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+via+RESTful+interface
>>>
>>> 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+via+RESTful+interface and keep the docu up to date there.
>>>
>>> Thoughts?
>>> --
>>> Galder Zamarreño
>>> Sr. Software Engineer
>>> Infinispan, JBoss Cache
>>>
>>>
>>> _______________________________________________
>>> infinispan-dev mailing list
>>> [hidden email]
>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>
>> _______________________________________________
>> infinispan-dev mailing list
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
> --
> Galder Zamarreño
> Sr. Software Engineer
> Infinispan, JBoss Cache
>
>
> _______________________________________________
> infinispan-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/infinispan-dev


_______________________________________________
infinispan-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/infinispan-dev
Reply | Threaded
Open this post in threaded view
|

Re: [infinispan-dev] RESTful API docu

Galder Zamarreno
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 <[hidden email]> 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+via+RESTful+interface
>>>>
>>>> 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+via+RESTful+interface and keep the docu up to date there.
>>>>
>>>> Thoughts?
>>>> --
>>>> Galder Zamarreño
>>>> Sr. Software Engineer
>>>> Infinispan, JBoss Cache
>>>>
>>>>
>>>> _______________________________________________
>>>> infinispan-dev mailing list
>>>> [hidden email]
>>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>>
>>> _______________________________________________
>>> infinispan-dev mailing list
>>> [hidden email]
>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>
>> --
>> Galder Zamarreño
>> Sr. Software Engineer
>> Infinispan, JBoss Cache
>>
>>
>> _______________________________________________
>> infinispan-dev mailing list
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
>
> _______________________________________________
> infinispan-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/infinispan-dev

--
Galder Zamarreño
Sr. Software Engineer
Infinispan, JBoss Cache


_______________________________________________
infinispan-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/infinispan-dev
Reply | Threaded
Open this post in threaded view
|

Re: [infinispan-dev] RESTful API docu

Pete Muir
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 <[hidden email]> 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+via+RESTful+interface
>>>>>
>>>>> 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+via+RESTful+interface and keep the docu up to date there.
>>>>>
>>>>> Thoughts?
>>>>> --
>>>>> Galder Zamarreño
>>>>> Sr. Software Engineer
>>>>> Infinispan, JBoss Cache
>>>>>
>>>>>
>>>>> _______________________________________________
>>>>> infinispan-dev mailing list
>>>>> [hidden email]
>>>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>>>
>>>> _______________________________________________
>>>> infinispan-dev mailing list
>>>> [hidden email]
>>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>>
>>> --
>>> Galder Zamarreño
>>> Sr. Software Engineer
>>> Infinispan, JBoss Cache
>>>
>>>
>>> _______________________________________________
>>> infinispan-dev mailing list
>>> [hidden email]
>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>
>>
>> _______________________________________________
>> infinispan-dev mailing list
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
> --
> Galder Zamarreño
> Sr. Software Engineer
> Infinispan, JBoss Cache
>
>
> _______________________________________________
> infinispan-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/infinispan-dev


_______________________________________________
infinispan-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/infinispan-dev
Reply | Threaded
Open this post in threaded view
|

Re: [infinispan-dev] RESTful API docu

Manik Surtani
+1

On 4 Jul 2011, at 11:30, Pete Muir wrote:

> 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 <[hidden email]> 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+via+RESTful+interface
>>>>>>
>>>>>> 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+via+RESTful+interface and keep the docu up to date there.
>>>>>>
>>>>>> Thoughts?
>>>>>> --
>>>>>> Galder Zamarreño
>>>>>> Sr. Software Engineer
>>>>>> Infinispan, JBoss Cache
>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> infinispan-dev mailing list
>>>>>> [hidden email]
>>>>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>>>>
>>>>> _______________________________________________
>>>>> infinispan-dev mailing list
>>>>> [hidden email]
>>>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>>>
>>>> --
>>>> Galder Zamarreño
>>>> Sr. Software Engineer
>>>> Infinispan, JBoss Cache
>>>>
>>>>
>>>> _______________________________________________
>>>> infinispan-dev mailing list
>>>> [hidden email]
>>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>>
>>>
>>> _______________________________________________
>>> infinispan-dev mailing list
>>> [hidden email]
>>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>>
>> --
>> Galder Zamarreño
>> Sr. Software Engineer
>> Infinispan, JBoss Cache
>>
>>
>> _______________________________________________
>> infinispan-dev mailing list
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
>
> _______________________________________________
> infinispan-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/infinispan-dev

--
Manik Surtani
[hidden email]
twitter.com/maniksurtani

Lead, Infinispan
http://www.infinispan.org




_______________________________________________
infinispan-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/infinispan-dev