spring-projects/spring-boot — pull request #508 by snicoll (2014-03-17 19:02:36+00:00)
Title: Review first 8 parts of the doc

This commit mostly fixes typos but also improves slightly specific areas, adding links when it make sense. You should double check as what I think to be a typo may not be in practice.

Reviewing the first 100 pages also lead to the following questions/remarks that might help improving the docs:

* You may want to review "lets" vs. "let's" as I am not convinced it is consistently used
* There's an overuse of quotes where italic style may be more appropriate. In particular, generated references already provide quotes so you often end up with double quotes at the end, something like `the “Section 62.1, “Build an executable archive with Ant””`
* The link to parts are not working with the pdf output. Not sure we should be too concerned about it
* The _note_ in section 19.2 5 (fluent builder api) is a bit advanced compared to a very accessible documentation so far. Maybe it should be revisited
* The example of multi YAML documents in section 20.5 is not intuitive unless you know the YALM format already. Adding an extra profile definition in that sample would help
* Section 22.4: the comment for the PID attribute is worth a second look (what not already provided mean here?)
* Section 26.1: if you depend on the parent pom it's not easy to replace those dependencies because they are forced. You can change the version if you want but you can't easily remove mockito to replace it by another mocking library
* Section 26.2: I think that this notion of `integration-test` is not really how it's being used out there. A lot of people are writing unit tests that start the spring application context and they don't call them integration tests. That notion is more related to actually starting a container and invoke requests against it.
* Section 34.4: I have no idea if that has been raised already but there should be a simple way to disable that channel and the generation of those messages if you don't care about them. Other features in that same section have an easy boolean switch
* Section 37 on error handling is too light and deserves more explanation
* `@EnableJmsMessaging` would be revisited when Spring's JMS annotated support is finalized, scheduled for 4.1
* (low) The pdf output has too many "blank pages" where we basically introduce one part with 3 lines...

Other than that, I really like what I read so far: it's consistent and easy to grasp.