Mentioning beans.xml in our guides

[csokol]

I've just noticed that the only point in our docs that we talk about the beans.xml file is in the migration guide. I know we're already logging if the user forget to add the file in its application, but I think it makes sense to explain that every application must add this file. What do you think?

[garcia-jj]

The beans.xml isn't mandatory, right? CDI will scan automatically using bean-discovery-mode=annotated if file isn't found.

But there is no reason to not mention beans.xml. I agree with this issue. May be we can add in the 1 minute guide pages a snippet of beans.xml.

[Turini]

yes, this is not required in app servers, but I agree that is important to add in our docs.

[garcia-jj]

May I do it? Which pages we can add?

[Turini]

Sure! I think we can add only at dependencies-and-pre-requisites page.
Since this page will be highlighted at one/ten minute guides. What u think?

[csokol]

I think it's important to mention in one/ten minute guides, since the idea
of these pages is to teach how to start using vraptor after adding its jar
and dependencies to the classpath.

My idea is that, without any knowledge about the framework, someone should
be able to start using it after reading the one minute guide. This is the
purpose of this guide, right?

Btw, taking a look in our docs, I think we should always provide a "next
steps" section in the end of each page (or enumerate the docs sections),
right now we don't have a "linearity" in our docs, which is something
important when you are starting to learn something (rails guides and docker
docs does that).

Chico Sokol

On Tue, Oct 7, 2014 at 8:40 AM, Rodrigo Turini [email protected]
wrote:

Sure! I think we can add only at dependencies-and-pre-requisites page.
Since this page will be highlighted at one/ten minute guides. What u think?

—
Reply to this email directly or view it on GitHub
#815 (comment).

[garcia-jj]

I like about next steps. 👌

[renanigt]

I totally agree with @csokol
Em 07/10/2014 20:17, "Otávio Garcia" [email protected] escreveu:

I like about next steps. [image: 👌]

—
Reply to this email directly or view it on GitHub
#815 (comment).

[Turini]

I think it's important to mention in one/ten minute guides, since the idea of these pages is to teach how to start using vraptor after adding its jar and dependencies to the classpath.

So we should also add info about validations.xml, and other mandatory stuff? There is a page for it, dependencies-and-pre-requisites! Highlighting this page at initial guides would be enough.

My idea is that, without any knowledge about the framework, someone should be able to start using it after reading the one minute guide. This is the purpose of this guide, right?

No, it isn't. The purpose of this guides is to teach the framework basics (features, conventions and behaviors). It must be as simple as possible.

Users should be able to start using VRaptor after reading this guides adding a well visible link to dependencies-and-pre-requisites page on the first paragraph of each one.

+1 about the next steps

[garcia-jj]

@Turini your comment about 1/10 minute guide are true. But I agree with @csokol too. User will read 2 pages with vraptor code but without any information how to prepare your environment. Of course its not good to replicate text in many pages about environment configuration, but may we can add some paragraph in the top of both pages like this:

In this page we will show to you how easy to use vraptor in your projects. If you prefer, you can check our dependencies page before.

[Turini]

this is exactly my point :) we shouldn't to replicate the content, only add a paragraph in the top of initial guides linking to dependencies and pre requisites page.

[csokol]

I don't like the replication either, but then I think we are changing the
focus of those guides from vraptor 3 to 4. It seems that the vraptor 3
guides was enough for start using the framework:
http://vraptor3.vraptor.org/en/docs/one-minute-guide/

Is validation.xml mandatory? Or is it required only when using Bean
Validation apis?

Chico Sokol

On Wed, Oct 8, 2014 at 1:57 PM, Rodrigo Turini [email protected]
wrote:

this is exactly my point :) we shouldn't to replicate the content, only
add a paragraph in the top of initial guides linking to dependencies and
pre requisites page.

—
Reply to this email directly or view it on GitHub
#815 (comment).

[Turini]

It seems that the vraptor 3 guides was enough for start using the framework

adding the paragraph about pre requisites VRaptor 4's guides will too... no need to
replicate :) Do you thing it will not be clear enough? Think about other requisites, why
talk about beans.xml and not about the weld listener? and about the weld mandatory
dependencies? the same with bean-validator dependency... why beans.xml info is
more important than the other mandatory stuff? Users must to know about all of them
to start using VRaptor... right? Adding only the beans.xml info would not be enough

[garcia-jj]

@csokol, validation.xml is only needed if you want to override default behavior from bean validation. In appservers bean validation automatically trigger method validation for managed beans. So we use validation.xml only to disable this validation under appservers, to allow us to validate internally using our classes.

[csokol]

Ok, you won :-)

I think it wouldn't be practical to mention all those requirements.

So we should definitely link to the dependencies page. Besides that, what
do you think of adding a paragraph like that in the one minute guide
(copied from vr3 docs):

You can start your project based on vraptor-blank-project, available on
. It contains all required jar dependencies, and the minimal web.xml
configuration for working with VRaptor

Chico Sokol

On Thu, Oct 9, 2014 at 2:00 PM, Otávio Garcia [email protected]
wrote:

@csokol https://github.com/csokol, validation.xml is only needed if you
want to override default behavior from bean validation. In appservers bean
validation automatically trigger method validation for managed beans. So we
use validation.xml only to disable this validation under appservers, to
allow us to validate internally using our classes.

—
Reply to this email directly or view it on GitHub
#815 (comment).

[garcia-jj]

@csokol I think you quote my email by mistake, because my quoted message is only about validation.xml :).

I agree with you, because I think that we can refactor our docs. But I also agree with @Turini too. May be we can add a simple note with only mandatory dependencies, a very small text. I agree that is not the best users touch in the code without know about how to configure.

And I think we can simple drop the 10 minute guide, because all you can see in 10 minute guide are detailed in next pages.

What you think guys?

[Turini]

what do you think of adding a paragraph like that in [...]

I think it would be really nice, good point @csokol

we can simple drop the ten minutes guide [...]

I'd keep the guide, but refactoring to use jungle examples (as you've proposed before)
This is a simple and fast preview of important features (better described in another sessions)
What do you thing @garcia-jj @csokol?