Re: [infinispan-dev] Documentation code snippets

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_... ----- Forwarded Message ----- > From: "Jiri Holusa" <jholusa(a)redhat.com&gt; > To: "infinispan-internal" <infinispan-internal(a)redhat.com&gt; > 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/do... > [2] > https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/... > > _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev