Vert.x Patterns documentation project

[aschrijver]

This is like #61 but then focuses on the 'guide' part and having it as a separate gh-pages (or similar) Github project, where everyone can contribute/

Additional to what is described in #61 the focus should be on architecture concepts and advanced uses of Vert.x (whereas vertx-examples serves more as a collection of 'hello world's' demonstrating individual product features).

Candidates for inclusion:

• Vert.x real-world application / architecture / deployment scenario's (Yes, please..)
• Howto's for frequently asked forum questions ('How do I handle large files?')
• Advanced code snippets (e.g. asynchronous / reactive programming constructs, RxJava, streams with back-pressure, tips & tricks, etc.)
• Infrastructure, DevOps practices and guidelines (e.g. 'Deploying Vert.x on...', 'Docker + Consul + Hazelcast', etc.)
• Code generation templates (to use with vertx-codegen)
• Integrating with other technologies
• Theoretical concepts behind Vert.x and its modules (or pointers to them)

I think information is best presented using small, concise recipes and content creation should be easy. It would be nice to have templates available for various information types, so as to reduce the barrier for contributors that don't have writing documentation as their favourite pastime (most developers).

[pmlopes]

@aschrijver one of our google summer of code students is doing some work on this area:

Feel free to review and comment on our student work:

• https://github.com/sczyh30/vertx-blueprint-todo-backend
• https://github.com/sczyh30/vertx-blueprint-job-queue
• https://github.com/sczyh30/vertx-blueprint-microservice
• https://github.com/sczyh30/vertx-blueprint-order-processing-system

He is doing a great job and our goal is to later on update the website to have a a section with his articles describing the development of such applications and the code itself.

[pmlopes]

@aschrijver Of course this does not cover all your topics so your whishlist item is still relevant and valid ;)

[aschrijver]

Thanks, those are some cool upcoming projects! Interesting, and definitely along the gist of this issue. PS Might be a good idea to have a Plans section somewhere, so there can be discussion (in issues?) on what features would be most valuable to include, before writing the code. And others can contribute early.

[aschrijver]

Also a couple of projects should be renamed to reflect the architecture concept. I've never had the need for a todo-backend or order-processing blueprint, and assume I will not in the near future as well :wink:

More blueprint suggestions:

• vertx-blueprint-containerized-microservices (like microservice blueprint, but focus on the plural and container architecture)
• vertx-blueprint-isomorphic-web-application (SSR + dynamic SPA front-end)
• vertx-blueprint-event-sourcing (or full CQRS, would be interesting)
• vertx-blueprint-performance-monitoring (or tuning)
• vertx-blueprint-security (end-to-end attention to security aspects)

[vietj]

imho we should have two distincts guides:

1/ a more advanced guide about for the vertx developer, i.e the person that wants to extend the vertx ecosystem (Code generation templates, Integrating with other technologies) 2/ a cookbook / pattern guide for the end user for the rest you mentioned aiming also to answer often asked questions in forums (like how do I start 2 servers and get a single callback, etc...)

I started an effort a while ago and added some content recently (about Netty integration) that aims to collect some of these which are advanced / internals : https://github.com/vietj/vertx-materials and I think could address the point 1/.

[aschrijver]

Yes, indeed. Your site already served me well, especially Demystifying the event loop. That's the kind of theoretical background one needs when going from beginner Vert.x user to more advanced stuff.

I would like to add that part of my need for a Patterns project comes from the fact that the current manuals are primarily code-oriented. Interspersing them with some more conceptual diagrams and theory could be an idea. An example of this is the Apache Storm docs:

• http://storm.apache.org/releases/2.0.0-SNAPSHOT/Understanding-the-parallelism-of-a-Storm-topology.html
• http://storm.apache.org/releases/2.0.0-SNAPSHOT/Guaranteeing-message-processing.html

[javadevmtl]

I think more info on reactive would be nice also. Its nice to say you are reactive. But it kinda sucks to see that we have to go figure it on the rx java site and examples of the rx wraped versions of the vertx api dont really explain much.

Examples on how to do multiple http requests and how to join them.

I always found when.vertx more intuitive...

[nickscodes]

+1!

[pmlopes]

Thishas been handled by the new org on github: https://github.com/vertx-howtos