spring-projects
Update docs to reduce clutter and cater to specific audience
One of my biggest complaints against the Spring integration docs is that I've to sift through a bunch of XML configuration examples, @Bean annotation examples, and Java DSL examples, all at the same time. For any user, they're looking for a particular type of configuration, and having all 3 is not helpful at all. Not to mention, the docs still lack sufficient Java DSL examples, whereas it can be safely said that XML configuration is rarely, if at all, used anymore.
My proposal is that the docs are updated such that every code block comes with 3 tabs - namely, XML, Java and DSL. Upon clicking a particular tab, the user can find the style of configuration easily and simply. This will also enforce gradual migration of all examples to Java DSL.
I believe some other Spring projects have already gone this route, although I don't have a link handy for citation.
We understand, but it's a huge task to rework the entire document and we have limited resources. Contributions are always welcome.
We try to address individual requests on a request-by-request.
That said, revamping the SI reference along the lines you suggest is on the roadmap for 2018.
However, you might be surprised at how many folks still prefer XML configuration for Spring Integration apps.
If you provide a template like I suggested, I will try to make contributions as time permits. I need a starting point. As for XML, I figure organizational bureaucracy or “if it’s aint broken” menatality might be the reasons for it’s continued usage, but for new apps, it’s very unlikely. The tabs should help in that regard.
That's really an interesting and useful suggestion. Only the problem that we don't know such a template.
@Buzzardo,
Any ideas on the matter? Is there some ASCIDoc tricks to make some kind of tabs on the page?
Nevertheless I think there would be really just enough to follow the way we go: via separate sections. For example: https://docs.spring.io/spring-integration/docs/5.0.0.RELEASE/reference/html/messaging-endpoints-chapter.html#logging-channel-adapter.
The point is that we still support PDF and ePub formats for the Reference Manual, not only HTML. So, some JavaScript magics might not be enough. WDYT, @asarkar ?
artembilan See the batch docs - notice the little Java/XML switch at the top.
I spoke to @Buzzardo at SpringOne Platform and our documents are on his list to work on this year.
We're adopting a toggle to show XML configuration or Java configuration. It works through a combination of Asciidoc configuration and custom JavaScript. We definitely want to add that feature to all of our documentation, including that for Spring Integration. (The toggle can work with any number of distinctions, but XML versus Java is where we are at present.)
There's a fair bit of work involved. Each example has to be marked as being XML or Java, so that the toggle picks it up correctly. Also, other content (usually the paragraphs that explain an example but sometimes other content, too) has to be marked as well - again, so that you won't see content about XML configuration if you want to see content about Java configuration.
Finally, and I can't stress this enough, the content has to be revised so that it still makes sense after big blocks of it get excluded by the toggle. Often, that means writing more content and re-writing other content. Some of that is definitely additional examples. (More sample code is always welcome, by the way.)
In short, we're headed in that direction, but it's a pile of work, so it can't happen overnight.
I'm glad to see community interest. Thank you.
OK. But the story is about each sample, not the whole chapter. Plus I have also mentioned PDF. Not sure that such a switch is possible there... Or are we not going to support it anymore as I can't find such one for the mentioned Spring Batch?..
At present, it's a chapter-by-chapter toggle. We haven't looked at putting it on each sample. The trouble is that we have content other than samples that is tied to either XML or Java. Consequently, we want to include and exclude paragraphs and even headings based on the toggle, which mandates a chapter-by-chapter approach (or a toggle for the whole book if you use the single-file version).
We don't presently plan to put the toggle in PDF output.
You can see the current version of the toggle working in Spring Batch here: https://docs.spring.io/spring-batch/4.0.x/reference/html/job.html#configureJob
I am almost done refactoring how that toggle works (so that it doesn't interfere with a collapsing ToC that we're also adding) and what it looks like, but the core functionality is the same. Expect to see both the toggle and the collapsing ToC across all Spring reference documentation at some point in the near future (this year, barring disasters).
@Buzzardo - I don't know if it will take much more effort, but in Spring Integration we have 3 configuration methods; see here for an example. So, ideally, a 3-way switch would be needed. If it's too hard we can put both Java-style configs on the Java side.
@garyrussell I kept your three-choice need in mind when I refactored the toggle. It handles an arbitrary number of options (two, three, thirteen, whatever).
(I've finished the refactoring, really. I'm at the point of getting it reviewed, which may mean some tweaking, but the core of it works.)
Hello
I want give support about this situation, I enjoy work around documentation.
Because I want do the right things, I have the following consults
- What happen (if exists the scenario) if there is no a way to create an example with the three forms. For example, for the situation X, there are only for XML and Java (no DSL)
- Exists a branch where all the examples are managed? it to avoid upload configuration that does not work. I mean, I am assuming that currently for each snippet code of XML available throughout the current documentation about configuration are available in action throughout the modules through
@Testing
I think we are on our way to this requirement. See for example WebFlux chapter: https://docs.spring.io/spring-integration/docs/current/reference/html/webflux.html#webflux-inbound.
There is still a lot to rework in style, but I treat this issue as fixed.
Contribution is still welcome since there are many samples in the docs which are not covered.