[infinispan-dev] Documentation code snippets

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

[infinispan-dev] Documentation code snippets

Jiri Holusa
Moving this to infinispan-dev.

I've just issued a PR [1], where I setup the code snippets generation. It was actually pretty easy. I started implementing it for the configuration part of the documentation and I came across following findings/issues.

There were more votes for option 2 (see the previous mail for detail, in summary using existing testsuite), hence I started with that. Pretty shortly I see following issues:
* XML configuration - since we want to have the <infinispan> element there in the configuration, I have to do one XML file per one configuration code snippet -> the number of files will grow and will mess up the "normal" testsuite
* IMHO biggest problem - our testsuite is usually not written in "documentation simplicity". For example, in testsuite we barely (= never) do "EmbeddedCacheManager cacheManager = new DefaultCacheManager("...");", we obtain the cache manager by some helper method. While this is great for testing, you don't want to have this in documentation as it should be simple and straightforward. Another example would be [2]. Look at the programmatic configuration snippets. In the testsuite, we usually don't have that trivial setup, not so comprehensively written somewhere.
* When you want to introduce a new code snippet, how can you be sure that the snippet is not somewhere in the testsuite already, but written a bit differently? I encountered this right from the beginning, search the test classes and looking for "good enough" code snippet that I could use.

Together it seems to me that it will mess up the testsuite quite a bit, make the maintenance of documentation harder and will significantly prolong the time needed for writing new documentation. What do you think? How about we went the same way as Hibernate (option 1 in first email) - creating separate documentation testsuite that is as simple as possible, descriptive and straightforward.

I don't really care, which option we choose, I will implement it either way, but I wanted to show that there are some pitfalls of the option 2 as well :(

Cheers,
Jiri

[1] https://github.com/infinispan/infinispan/pull/5115
[2] http://infinispan.org/docs/stable/user_guide/user_guide.html#configuring_caches_programmatically



----- Forwarded Message -----

> From: "Jiri Holusa" <[hidden email]>
> To: "infinispan-internal" <[hidden email]>
> Sent: Friday, April 7, 2017 6:33:53 PM
> Subject: [infinispan-internal] Documentation code snippets
>
> Hi everybody,
>
> during the documentation review for JDG 7.1 GA, I came across this little
> thing.
>
> Having a good documentation is IMHO crucial for people to like our technology
> and the key point is having code snippets in the documentation up to date
> and working. During review of my parts, I found out many and many outdated
> code snippets, either non-compilable or using deprecated methods. I would
> like to eliminate this issue in the future, so it would make our
> documentation better and also remove burden when doing documentation review.
>
> I did some research and I found out that Hibernate team (thanks Radim, Sanne
> for the information) does a very cool thing and that is that the code
> snippets are taken right from testsuite. This way they know that the code
> snippet can always compile and also make sure that it's working properly. I
> would definitely love to see the same in Infinispan.
>
> It works extremely simply that you mark by comment in the test the part, you
> want to include in the documentation, see an example here for the AsciiDoc
> part [1] and here for the test part [2]. There are two ways of how to
> organize that:
> 1) create a separate "documentation testsuite", with as simple as possible
> test classes - Hibernate team does it this way. Pros: documentation is
> easily separated. Cons: possible duplication.
> 2) use existing testsuite, marking the parts in the existing testsuite. Pros:
> no duplication. Cons: documentation snippets are spread all across the
> testsuite.
>
> I would definitely volunteer to make this happen in Infinispan
> documentation.
>
> What do you guys think about it?
>
> Cheers,
> Jiri
>
> [1]
> https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch03.asciidoc
> [2]
> https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/test/java/org/hibernate/userguide/caching/FirstLevelCacheTest.java
>
>
_______________________________________________
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] Documentation code snippets

Dennis Reed
Definitely #1.  They serve two completely separate purposes.

I'm glad to see this, as incorrect examples in documentation is a pet
peeve of mine.  :)

-Dennis


On 05/03/2017 09:14 AM, Jiri Holusa wrote:

> Moving this to infinispan-dev.
>
> I've just issued a PR [1], where I setup the code snippets generation. It was actually pretty easy. I started implementing it for the configuration part of the documentation and I came across following findings/issues.
>
> There were more votes for option 2 (see the previous mail for detail, in summary using existing testsuite), hence I started with that. Pretty shortly I see following issues:
> * XML configuration - since we want to have the <infinispan> element there in the configuration, I have to do one XML file per one configuration code snippet -> the number of files will grow and will mess up the "normal" testsuite
> * IMHO biggest problem - our testsuite is usually not written in "documentation simplicity". For example, in testsuite we barely (= never) do "EmbeddedCacheManager cacheManager = new DefaultCacheManager("...");", we obtain the cache manager by some helper method. While this is great for testing, you don't want to have this in documentation as it should be simple and straightforward. Another example would be [2]. Look at the programmatic configuration snippets. In the testsuite, we usually don't have that trivial setup, not so comprehensively written somewhere.
> * When you want to introduce a new code snippet, how can you be sure that the snippet is not somewhere in the testsuite already, but written a bit differently? I encountered this right from the beginning, search the test classes and looking for "good enough" code snippet that I could use.
>
> Together it seems to me that it will mess up the testsuite quite a bit, make the maintenance of documentation harder and will significantly prolong the time needed for writing new documentation. What do you think? How about we went the same way as Hibernate (option 1 in first email) - creating separate documentation testsuite that is as simple as possible, descriptive and straightforward.
>
> I don't really care, which option we choose, I will implement it either way, but I wanted to show that there are some pitfalls of the option 2 as well :(
>
> Cheers,
> Jiri
>
> [1] https://github.com/infinispan/infinispan/pull/5115
> [2] http://infinispan.org/docs/stable/user_guide/user_guide.html#configuring_caches_programmatically
>
>
>
> ----- Forwarded Message -----
>> From: "Jiri Holusa" <[hidden email]>
>> To: "infinispan-internal" <[hidden email]>
>> Sent: Friday, April 7, 2017 6:33:53 PM
>> Subject: [infinispan-internal] Documentation code snippets
>>
>> Hi everybody,
>>
>> during the documentation review for JDG 7.1 GA, I came across this little
>> thing.
>>
>> Having a good documentation is IMHO crucial for people to like our technology
>> and the key point is having code snippets in the documentation up to date
>> and working. During review of my parts, I found out many and many outdated
>> code snippets, either non-compilable or using deprecated methods. I would
>> like to eliminate this issue in the future, so it would make our
>> documentation better and also remove burden when doing documentation review.
>>
>> I did some research and I found out that Hibernate team (thanks Radim, Sanne
>> for the information) does a very cool thing and that is that the code
>> snippets are taken right from testsuite. This way they know that the code
>> snippet can always compile and also make sure that it's working properly. I
>> would definitely love to see the same in Infinispan.
>>
>> It works extremely simply that you mark by comment in the test the part, you
>> want to include in the documentation, see an example here for the AsciiDoc
>> part [1] and here for the test part [2]. There are two ways of how to
>> organize that:
>> 1) create a separate "documentation testsuite", with as simple as possible
>> test classes - Hibernate team does it this way. Pros: documentation is
>> easily separated. Cons: possible duplication.
>> 2) use existing testsuite, marking the parts in the existing testsuite. Pros:
>> no duplication. Cons: documentation snippets are spread all across the
>> testsuite.
>>
>> I would definitely volunteer to make this happen in Infinispan
>> documentation.
>>
>> What do you guys think about it?
>>
>> Cheers,
>> Jiri
>>
>> [1]
>> https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch03.asciidoc
>> [2]
>> https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/test/java/org/hibernate/userguide/caching/FirstLevelCacheTest.java
>>
>>
> _______________________________________________
> 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] Documentation code snippets

Sebastian Laskawiec
In reply to this post by Jiri Holusa
Hey Jiri,

Very good investigation. I was all for option #2 (use existing testsuite) but now I'm leaning towards option #1 (separate testsuite). 

I believe there are 3 main parts to be tested and synced with documentation - Hot Rod Client, Infinispan Server and Embedded Mode. The first two can be tested together I think. To some extend this is already implemented in ExampleConfigsIT [1]. The Embedded Mode is much harder to test in my opinion, since the tests are spread all around the repo. I guess this will be the main challenge of this task.

Thanks,
Sebastian

[1] https://github.com/infinispan/infinispan/blob/master/server/integration/testsuite/src/test/java/org/infinispan/server/test/configs/ExampleConfigsIT.java

On Wed, May 3, 2017 at 3:20 PM Jiri Holusa <[hidden email]> wrote:
Moving this to infinispan-dev.

I've just issued a PR [1], where I setup the code snippets generation. It was actually pretty easy. I started implementing it for the configuration part of the documentation and I came across following findings/issues.

There were more votes for option 2 (see the previous mail for detail, in summary using existing testsuite), hence I started with that. Pretty shortly I see following issues:
* XML configuration - since we want to have the <infinispan> element there in the configuration, I have to do one XML file per one configuration code snippet -> the number of files will grow and will mess up the "normal" testsuite
* IMHO biggest problem - our testsuite is usually not written in "documentation simplicity". For example, in testsuite we barely (= never) do "EmbeddedCacheManager cacheManager = new DefaultCacheManager("...");", we obtain the cache manager by some helper method. While this is great for testing, you don't want to have this in documentation as it should be simple and straightforward. Another example would be [2]. Look at the programmatic configuration snippets. In the testsuite, we usually don't have that trivial setup, not so comprehensively written somewhere.
* When you want to introduce a new code snippet, how can you be sure that the snippet is not somewhere in the testsuite already, but written a bit differently? I encountered this right from the beginning, search the test classes and looking for "good enough" code snippet that I could use.

Together it seems to me that it will mess up the testsuite quite a bit, make the maintenance of documentation harder and will significantly prolong the time needed for writing new documentation. What do you think? How about we went the same way as Hibernate (option 1 in first email) - creating separate documentation testsuite that is as simple as possible, descriptive and straightforward.

I don't really care, which option we choose, I will implement it either way, but I wanted to show that there are some pitfalls of the option 2 as well :(

Cheers,
Jiri

[1] https://github.com/infinispan/infinispan/pull/5115
[2] http://infinispan.org/docs/stable/user_guide/user_guide.html#configuring_caches_programmatically



----- Forwarded Message -----
> From: "Jiri Holusa" <[hidden email]>
> To: "infinispan-internal" <[hidden email]>
> Sent: Friday, April 7, 2017 6:33:53 PM
> Subject: [infinispan-internal] Documentation code snippets
>
> Hi everybody,
>
> during the documentation review for JDG 7.1 GA, I came across this little
> thing.
>
> Having a good documentation is IMHO crucial for people to like our technology
> and the key point is having code snippets in the documentation up to date
> and working. During review of my parts, I found out many and many outdated
> code snippets, either non-compilable or using deprecated methods. I would
> like to eliminate this issue in the future, so it would make our
> documentation better and also remove burden when doing documentation review.
>
> I did some research and I found out that Hibernate team (thanks Radim, Sanne
> for the information) does a very cool thing and that is that the code
> snippets are taken right from testsuite. This way they know that the code
> snippet can always compile and also make sure that it's working properly. I
> would definitely love to see the same in Infinispan.
>
> It works extremely simply that you mark by comment in the test the part, you
> want to include in the documentation, see an example here for the AsciiDoc
> part [1] and here for the test part [2]. There are two ways of how to
> organize that:
> 1) create a separate "documentation testsuite", with as simple as possible
> test classes - Hibernate team does it this way. Pros: documentation is
> easily separated. Cons: possible duplication.
> 2) use existing testsuite, marking the parts in the existing testsuite. Pros:
> no duplication. Cons: documentation snippets are spread all across the
> testsuite.
>
> I would definitely volunteer to make this happen in Infinispan
> documentation.
>
> What do you guys think about it?
>
> Cheers,
> Jiri
>
> [1]
> https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch03.asciidoc
> [2]
> https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/test/java/org/hibernate/userguide/caching/FirstLevelCacheTest.java
>
>
_______________________________________________
infinispan-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/infinispan-dev
--

SEBASTIAN ŁASKAWIEC

INFINISPAN DEVELOPER


_______________________________________________
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] Documentation code snippets

Jiri Holusa
Hi Sebastian,

yes, you're right. I think the best way would be to go with option 2 making it comprehensive, clean and transparent. I will issue another preview PR soon that would contain some part from Hot Rod Client, ISPN Serven and Embedded mode snippets making it as an example, what it would look like in the end.

If anybody else has other opinions, please jump in, thanks.
Jiri


----- Original Message -----

> From: "Sebastian Laskawiec" <[hidden email]>
> To: "infinispan -Dev List" <[hidden email]>
> Sent: Friday, May 5, 2017 3:48:43 PM
> Subject: Re: [infinispan-dev] Documentation code snippets
>
> Hey Jiri,
>
> Very good investigation. I was all for option #2 (use existing testsuite) but
> now I'm leaning towards option #1 (separate testsuite).
>
> I believe there are 3 main parts to be tested and synced with documentation -
> Hot Rod Client, Infinispan Server and Embedded Mode. The first two can be
> tested together I think. To some extend this is already implemented in
> ExampleConfigsIT [1]. The Embedded Mode is much harder to test in my
> opinion, since the tests are spread all around the repo. I guess this will
> be the main challenge of this task.
>
> Thanks,
> Sebastian
>
> [1]
> https://github.com/infinispan/infinispan/blob/master/server/integration/testsuite/src/test/java/org/infinispan/server/test/configs/ExampleConfigsIT.java
>
> On Wed, May 3, 2017 at 3:20 PM Jiri Holusa < [hidden email] > wrote:
>
>
> Moving this to infinispan-dev.
>
> I've just issued a PR [1], where I setup the code snippets generation. It was
> actually pretty easy. I started implementing it for the configuration part
> of the documentation and I came across following findings/issues.
>
> There were more votes for option 2 (see the previous mail for detail, in
> summary using existing testsuite), hence I started with that. Pretty shortly
> I see following issues:
> * XML configuration - since we want to have the <infinispan> element there in
> the configuration, I have to do one XML file per one configuration code
> snippet -> the number of files will grow and will mess up the "normal"
> testsuite
> * IMHO biggest problem - our testsuite is usually not written in
> "documentation simplicity". For example, in testsuite we barely (= never) do
> "EmbeddedCacheManager cacheManager = new DefaultCacheManager("...");", we
> obtain the cache manager by some helper method. While this is great for
> testing, you don't want to have this in documentation as it should be simple
> and straightforward. Another example would be [2]. Look at the programmatic
> configuration snippets. In the testsuite, we usually don't have that trivial
> setup, not so comprehensively written somewhere.
> * When you want to introduce a new code snippet, how can you be sure that the
> snippet is not somewhere in the testsuite already, but written a bit
> differently? I encountered this right from the beginning, search the test
> classes and looking for "good enough" code snippet that I could use.
>
> Together it seems to me that it will mess up the testsuite quite a bit, make
> the maintenance of documentation harder and will significantly prolong the
> time needed for writing new documentation. What do you think? How about we
> went the same way as Hibernate (option 1 in first email) - creating separate
> documentation testsuite that is as simple as possible, descriptive and
> straightforward.
>
> I don't really care, which option we choose, I will implement it either way,
> but I wanted to show that there are some pitfalls of the option 2 as well :(
>
> Cheers,
> Jiri
>
> [1] https://github.com/infinispan/infinispan/pull/5115
> [2]
> http://infinispan.org/docs/stable/user_guide/user_guide.html#configuring_caches_programmatically
>
>
>
> ----- Forwarded Message -----
> > From: "Jiri Holusa" < [hidden email] >
> > To: "infinispan-internal" < [hidden email] >
> > Sent: Friday, April 7, 2017 6:33:53 PM
> > Subject: [infinispan-internal] Documentation code snippets
> >
> > Hi everybody,
> >
> > during the documentation review for JDG 7.1 GA, I came across this little
> > thing.
> >
> > Having a good documentation is IMHO crucial for people to like our
> > technology
> > and the key point is having code snippets in the documentation up to date
> > and working. During review of my parts, I found out many and many outdated
> > code snippets, either non-compilable or using deprecated methods. I would
> > like to eliminate this issue in the future, so it would make our
> > documentation better and also remove burden when doing documentation
> > review.
> >
> > I did some research and I found out that Hibernate team (thanks Radim,
> > Sanne
> > for the information) does a very cool thing and that is that the code
> > snippets are taken right from testsuite. This way they know that the code
> > snippet can always compile and also make sure that it's working properly. I
> > would definitely love to see the same in Infinispan.
> >
> > It works extremely simply that you mark by comment in the test the part,
> > you
> > want to include in the documentation, see an example here for the AsciiDoc
> > part [1] and here for the test part [2]. There are two ways of how to
> > organize that:
> > 1) create a separate "documentation testsuite", with as simple as possible
> > test classes - Hibernate team does it this way. Pros: documentation is
> > easily separated. Cons: possible duplication.
> > 2) use existing testsuite, marking the parts in the existing testsuite.
> > Pros:
> > no duplication. Cons: documentation snippets are spread all across the
> > testsuite.
> >
> > I would definitely volunteer to make this happen in Infinispan
> > documentation.
> >
> > What do you guys think about it?
> >
> > Cheers,
> > Jiri
> >
> > [1]
> > https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch03.asciidoc
> > [2]
> > https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/test/java/org/hibernate/userguide/caching/FirstLevelCacheTest.java
> >
> >
> _______________________________________________
> infinispan-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/infinispan-dev
> --
>
>
> SEBASTIAN ŁASKAWIEC
>
> INFINISPAN DEVELOPER
>
> Red Hat EMEA
>
> _______________________________________________
> 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] Documentation code snippets

Tristan Tarrant-2
+1 for #2 from me too

Tristan

On 5/5/17 4:43 PM, Jiri Holusa wrote:

> Hi Sebastian,
>
> yes, you're right. I think the best way would be to go with option 2 making it comprehensive, clean and transparent. I will issue another preview PR soon that would contain some part from Hot Rod Client, ISPN Serven and Embedded mode snippets making it as an example, what it would look like in the end.
>
> If anybody else has other opinions, please jump in, thanks.
> Jiri
>
>
> ----- Original Message -----
>> From: "Sebastian Laskawiec" <[hidden email]>
>> To: "infinispan -Dev List" <[hidden email]>
>> Sent: Friday, May 5, 2017 3:48:43 PM
>> Subject: Re: [infinispan-dev] Documentation code snippets
>>
>> Hey Jiri,
>>
>> Very good investigation. I was all for option #2 (use existing testsuite) but
>> now I'm leaning towards option #1 (separate testsuite).
>>
>> I believe there are 3 main parts to be tested and synced with documentation -
>> Hot Rod Client, Infinispan Server and Embedded Mode. The first two can be
>> tested together I think. To some extend this is already implemented in
>> ExampleConfigsIT [1]. The Embedded Mode is much harder to test in my
>> opinion, since the tests are spread all around the repo. I guess this will
>> be the main challenge of this task.
>>
>> Thanks,
>> Sebastian
>>
>> [1]
>> https://github.com/infinispan/infinispan/blob/master/server/integration/testsuite/src/test/java/org/infinispan/server/test/configs/ExampleConfigsIT.java
>>
>> On Wed, May 3, 2017 at 3:20 PM Jiri Holusa < [hidden email] > wrote:
>>
>>
>> Moving this to infinispan-dev.
>>
>> I've just issued a PR [1], where I setup the code snippets generation. It was
>> actually pretty easy. I started implementing it for the configuration part
>> of the documentation and I came across following findings/issues.
>>
>> There were more votes for option 2 (see the previous mail for detail, in
>> summary using existing testsuite), hence I started with that. Pretty shortly
>> I see following issues:
>> * XML configuration - since we want to have the <infinispan> element there in
>> the configuration, I have to do one XML file per one configuration code
>> snippet -> the number of files will grow and will mess up the "normal"
>> testsuite
>> * IMHO biggest problem - our testsuite is usually not written in
>> "documentation simplicity". For example, in testsuite we barely (= never) do
>> "EmbeddedCacheManager cacheManager = new DefaultCacheManager("...");", we
>> obtain the cache manager by some helper method. While this is great for
>> testing, you don't want to have this in documentation as it should be simple
>> and straightforward. Another example would be [2]. Look at the programmatic
>> configuration snippets. In the testsuite, we usually don't have that trivial
>> setup, not so comprehensively written somewhere.
>> * When you want to introduce a new code snippet, how can you be sure that the
>> snippet is not somewhere in the testsuite already, but written a bit
>> differently? I encountered this right from the beginning, search the test
>> classes and looking for "good enough" code snippet that I could use.
>>
>> Together it seems to me that it will mess up the testsuite quite a bit, make
>> the maintenance of documentation harder and will significantly prolong the
>> time needed for writing new documentation. What do you think? How about we
>> went the same way as Hibernate (option 1 in first email) - creating separate
>> documentation testsuite that is as simple as possible, descriptive and
>> straightforward.
>>
>> I don't really care, which option we choose, I will implement it either way,
>> but I wanted to show that there are some pitfalls of the option 2 as well :(
>>
>> Cheers,
>> Jiri
>>
>> [1] https://github.com/infinispan/infinispan/pull/5115
>> [2]
>> http://infinispan.org/docs/stable/user_guide/user_guide.html#configuring_caches_programmatically
>>
>>
>>
>> ----- Forwarded Message -----
>>> From: "Jiri Holusa" < [hidden email] >
>>> To: "infinispan-internal" < [hidden email] >
>>> Sent: Friday, April 7, 2017 6:33:53 PM
>>> Subject: [infinispan-internal] Documentation code snippets
>>>
>>> Hi everybody,
>>>
>>> during the documentation review for JDG 7.1 GA, I came across this little
>>> thing.
>>>
>>> Having a good documentation is IMHO crucial for people to like our
>>> technology
>>> and the key point is having code snippets in the documentation up to date
>>> and working. During review of my parts, I found out many and many outdated
>>> code snippets, either non-compilable or using deprecated methods. I would
>>> like to eliminate this issue in the future, so it would make our
>>> documentation better and also remove burden when doing documentation
>>> review.
>>>
>>> I did some research and I found out that Hibernate team (thanks Radim,
>>> Sanne
>>> for the information) does a very cool thing and that is that the code
>>> snippets are taken right from testsuite. This way they know that the code
>>> snippet can always compile and also make sure that it's working properly. I
>>> would definitely love to see the same in Infinispan.
>>>
>>> It works extremely simply that you mark by comment in the test the part,
>>> you
>>> want to include in the documentation, see an example here for the AsciiDoc
>>> part [1] and here for the test part [2]. There are two ways of how to
>>> organize that:
>>> 1) create a separate "documentation testsuite", with as simple as possible
>>> test classes - Hibernate team does it this way. Pros: documentation is
>>> easily separated. Cons: possible duplication.
>>> 2) use existing testsuite, marking the parts in the existing testsuite.
>>> Pros:
>>> no duplication. Cons: documentation snippets are spread all across the
>>> testsuite.
>>>
>>> I would definitely volunteer to make this happen in Infinispan
>>> documentation.
>>>
>>> What do you guys think about it?
>>>
>>> Cheers,
>>> Jiri
>>>
>>> [1]
>>> https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch03.asciidoc
>>> [2]
>>> https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/test/java/org/hibernate/userguide/caching/FirstLevelCacheTest.java
>>>
>>>
>> _______________________________________________
>> infinispan-dev mailing list
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>> --
>>
>>
>> SEBASTIAN ŁASKAWIEC
>>
>> INFINISPAN DEVELOPER
>>
>> Red Hat EMEA
>>
>> _______________________________________________
>> 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
>

--
Tristan Tarrant
Infinispan Lead
JBoss, a division of Red Hat
_______________________________________________
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] Documentation code snippets

Alan Field
As confusing as this is, I agree with Tristan! :-)

----- Original Message -----

> From: "Tristan Tarrant" <[hidden email]>
> To: "infinispan -Dev List" <[hidden email]>, "Jiri Holusa" <[hidden email]>
> Sent: Friday, May 5, 2017 11:12:31 AM
> Subject: Re: [infinispan-dev] Documentation code snippets
>
> +1 for #2 from me too
>
> Tristan
>
> On 5/5/17 4:43 PM, Jiri Holusa wrote:
> > Hi Sebastian,
> >
> > yes, you're right. I think the best way would be to go with option 2 making
> > it comprehensive, clean and transparent. I will issue another preview PR
> > soon that would contain some part from Hot Rod Client, ISPN Serven and
> > Embedded mode snippets making it as an example, what it would look like in
> > the end.
> >
> > If anybody else has other opinions, please jump in, thanks.
> > Jiri
> >
> >
> > ----- Original Message -----
> >> From: "Sebastian Laskawiec" <[hidden email]>
> >> To: "infinispan -Dev List" <[hidden email]>
> >> Sent: Friday, May 5, 2017 3:48:43 PM
> >> Subject: Re: [infinispan-dev] Documentation code snippets
> >>
> >> Hey Jiri,
> >>
> >> Very good investigation. I was all for option #2 (use existing testsuite)
> >> but
> >> now I'm leaning towards option #1 (separate testsuite).
> >>
> >> I believe there are 3 main parts to be tested and synced with
> >> documentation -
> >> Hot Rod Client, Infinispan Server and Embedded Mode. The first two can be
> >> tested together I think. To some extend this is already implemented in
> >> ExampleConfigsIT [1]. The Embedded Mode is much harder to test in my
> >> opinion, since the tests are spread all around the repo. I guess this will
> >> be the main challenge of this task.
> >>
> >> Thanks,
> >> Sebastian
> >>
> >> [1]
> >> https://github.com/infinispan/infinispan/blob/master/server/integration/testsuite/src/test/java/org/infinispan/server/test/configs/ExampleConfigsIT.java
> >>
> >> On Wed, May 3, 2017 at 3:20 PM Jiri Holusa < [hidden email] > wrote:
> >>
> >>
> >> Moving this to infinispan-dev.
> >>
> >> I've just issued a PR [1], where I setup the code snippets generation. It
> >> was
> >> actually pretty easy. I started implementing it for the configuration part
> >> of the documentation and I came across following findings/issues.
> >>
> >> There were more votes for option 2 (see the previous mail for detail, in
> >> summary using existing testsuite), hence I started with that. Pretty
> >> shortly
> >> I see following issues:
> >> * XML configuration - since we want to have the <infinispan> element there
> >> in
> >> the configuration, I have to do one XML file per one configuration code
> >> snippet -> the number of files will grow and will mess up the "normal"
> >> testsuite
> >> * IMHO biggest problem - our testsuite is usually not written in
> >> "documentation simplicity". For example, in testsuite we barely (= never)
> >> do
> >> "EmbeddedCacheManager cacheManager = new DefaultCacheManager("...");", we
> >> obtain the cache manager by some helper method. While this is great for
> >> testing, you don't want to have this in documentation as it should be
> >> simple
> >> and straightforward. Another example would be [2]. Look at the
> >> programmatic
> >> configuration snippets. In the testsuite, we usually don't have that
> >> trivial
> >> setup, not so comprehensively written somewhere.
> >> * When you want to introduce a new code snippet, how can you be sure that
> >> the
> >> snippet is not somewhere in the testsuite already, but written a bit
> >> differently? I encountered this right from the beginning, search the test
> >> classes and looking for "good enough" code snippet that I could use.
> >>
> >> Together it seems to me that it will mess up the testsuite quite a bit,
> >> make
> >> the maintenance of documentation harder and will significantly prolong the
> >> time needed for writing new documentation. What do you think? How about we
> >> went the same way as Hibernate (option 1 in first email) - creating
> >> separate
> >> documentation testsuite that is as simple as possible, descriptive and
> >> straightforward.
> >>
> >> I don't really care, which option we choose, I will implement it either
> >> way,
> >> but I wanted to show that there are some pitfalls of the option 2 as well
> >> :(
> >>
> >> Cheers,
> >> Jiri
> >>
> >> [1] https://github.com/infinispan/infinispan/pull/5115
> >> [2]
> >> http://infinispan.org/docs/stable/user_guide/user_guide.html#configuring_caches_programmatically
> >>
> >>
> >>
> >> ----- Forwarded Message -----
> >>> From: "Jiri Holusa" < [hidden email] >
> >>> To: "infinispan-internal" < [hidden email] >
> >>> Sent: Friday, April 7, 2017 6:33:53 PM
> >>> Subject: [infinispan-internal] Documentation code snippets
> >>>
> >>> Hi everybody,
> >>>
> >>> during the documentation review for JDG 7.1 GA, I came across this little
> >>> thing.
> >>>
> >>> Having a good documentation is IMHO crucial for people to like our
> >>> technology
> >>> and the key point is having code snippets in the documentation up to date
> >>> and working. During review of my parts, I found out many and many
> >>> outdated
> >>> code snippets, either non-compilable or using deprecated methods. I would
> >>> like to eliminate this issue in the future, so it would make our
> >>> documentation better and also remove burden when doing documentation
> >>> review.
> >>>
> >>> I did some research and I found out that Hibernate team (thanks Radim,
> >>> Sanne
> >>> for the information) does a very cool thing and that is that the code
> >>> snippets are taken right from testsuite. This way they know that the code
> >>> snippet can always compile and also make sure that it's working properly.
> >>> I
> >>> would definitely love to see the same in Infinispan.
> >>>
> >>> It works extremely simply that you mark by comment in the test the part,
> >>> you
> >>> want to include in the documentation, see an example here for the
> >>> AsciiDoc
> >>> part [1] and here for the test part [2]. There are two ways of how to
> >>> organize that:
> >>> 1) create a separate "documentation testsuite", with as simple as
> >>> possible
> >>> test classes - Hibernate team does it this way. Pros: documentation is
> >>> easily separated. Cons: possible duplication.
> >>> 2) use existing testsuite, marking the parts in the existing testsuite.
> >>> Pros:
> >>> no duplication. Cons: documentation snippets are spread all across the
> >>> testsuite.
> >>>
> >>> I would definitely volunteer to make this happen in Infinispan
> >>> documentation.
> >>>
> >>> What do you guys think about it?
> >>>
> >>> Cheers,
> >>> Jiri
> >>>
> >>> [1]
> >>> https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch03.asciidoc
> >>> [2]
> >>> https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/test/java/org/hibernate/userguide/caching/FirstLevelCacheTest.java
> >>>
> >>>
> >> _______________________________________________
> >> infinispan-dev mailing list
> >> [hidden email]
> >> https://lists.jboss.org/mailman/listinfo/infinispan-dev
> >> --
> >>
> >>
> >> SEBASTIAN ŁASKAWIEC
> >>
> >> INFINISPAN DEVELOPER
> >>
> >> Red Hat EMEA
> >>
> >> _______________________________________________
> >> 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
> >
>
> --
> Tristan Tarrant
> Infinispan Lead
> JBoss, a division of Red Hat
> _______________________________________________
> 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