Reference Documentation Updated

[lucasward]

Over the last couple months, many of you on the forums have raised issues about the quality of the reference documentation. The chief complaints being that they fall short of covering all spring batch features, are not in-depth enough, and in some cases have been out of date. All of these are very real concerns, and I would like to apologize that they have not been given the proper amount of attention. I have worked extremely hard over the last couple of weeks (with help from Wayne Lund and Dave Syer) to get the documentation into shape for our upcoming 1.0 release. The first part of this effort has been completed and the latest docs have been pushed to the site:

http://static.springframework.org/sp...eference/html/

(Thanks go to Ben Hale for stepping in while Dave is at qCon in order to publish the docs)

In the latest documentation you can see that the first 3 chapters have been completely rewritten and should now be comprehensive. They cover an introduction to the framework, the 'domain language of batch' and a comprehensive chapter on all ItemReaders and ItemWriters in the framework. One note to make is that section 2.7 will likely be moved out of chapter 2 and into chapter 4 in the near future. There is also a chapter on the RepeatTemplate (chapter 5) available as well.

Many of you have provided great feedback about the framework in general, and I would like to ask that you do so for the documentation as well. If you are able, please look through the latest updates and reply to this thread with any thoughts you may have about the content. Please feel free to also raise jira issues as well, as we also use it to track documentation work.

Thanks for all your help in shaping Spring Batch,

-Lucas

[ndefreitas]

Hi,
Can you post a PDF version for us? It's easier when we're not connected.

[Dave Syer]

Nigel,

What did you mean by "post" the PDF? Can you follow this link (obviously not if you are not connected to the internet, but then you couldn't read this post if you weren't)?

http://static.springframework.org/sp...batch-docs.pdf

[madhav]

Is it only me or anybody else has the problem that one cant see any figures in the spring batch document?
For example I cant see Figure 1.1 on page 3. Printing the page didnt help either.
Im using Acrobat Reader 7.0

Thanks,
mAdHaV

[lucasward]

I see the same thing, that's probably some type of bug in the PDF generation, I'll look into it.

[sandrine]

Hi,

First I wish to thank you for all the work that you are doing.

I have read this documentation quickly and here are my remarks:

• I have the same problem as you to see the pictures.

• The table of features p30 seems to be empty.

• This documentation seems to mix informations about several old versions of spring batch; p21, there are some references about ItemProviderProcessTasklet, InputSourceItemProvider...that don't exist in m5 version.
  I saw the same things in the descriptions of the samples.

[Dave Syer]

I think you must have got hold of an old version. Can you clear your browser cache or something and try and download the new version?

[sandrine]

Sorry, you are right. But I can't get the new pdf because it seems that there is a cache in the proxy of my company that I can't clear.
I'm going to read the html version of documentation.

Thanks

[gaurav]

The best place for such detailed documentation is really the Javadocs - keeping the reference guide in synch with the source code becomes unmanageable if we commit to a complete description of all properties and methods in both places.

You can usually see the Javadocs in your IDE (e.g. using Spring IDE to create a job configuration, or in the source browser) as long as the source jars are available. That's what I use with all Spring projects.

[dkaminsky]

gaurav - That's not really true - the documentation for 1.0.x once it is complete will not change significantly. Updating the documentation for each major release is pretty standard.

That is, the 1.0.0 release will remain a branch in the repository for the foreseeable future, and will never change - when you pull 1.0.0, you are always pulling the same code with the same API. Therefore, the documentation corresponding to that branch won't ever have to change... the same goes for the API - the API generated for 1.0.0 won't change significantly until the next major release.