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" <jhol...@redhat.com>
>> To: "infinispan-internal" <infinispan-inter...@redhat.com>
>> 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
> infinispan-dev@lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
_______________________________________________
infinispan-dev mailing list
infinispan-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/infinispan-dev
