[weld-issues] [JBoss JIRA] Commented: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.

[Ondrej Zizka (JIRA)]

    [ https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12604840#comment-12604840 ] 

Ondrej Zizka commented on WELD-900:
-----------------------------------

{quote}
2.1.5. Interceptor binding types

You might be familiar with the use of interceptors in EJB 3.0. In Java EE 6, this functionality has been generalized to work with other managed beans. That's right, you no longer have to make your bean an EJB just to intercept its methods. Holler. So what does CDI have to offer above and beyond that? Well, quite a lot actually. Let's cover some background. 
{quote}

I don't think that assuming all readers are familiar with the use of interceptors.
The concept should be shortly explained, and maybe there can be a note that it originated in EJB 3.0.

Truth is, that it's covered that way in the chapter 9, but even in the introduction, I'd keep it that way.

> Docs: Improve Weld reference. Make it less poetic and more structured.
> ----------------------------------------------------------------------
>
>                 Key: WELD-900
>                 URL: https://issues.jboss.org/browse/WELD-900
>             Project: Weld
>          Issue Type: Bug
>          Components: Documentation
>            Reporter: Ondrej Zizka
>            Assignee: Pete Muir
>
> It's nice to have a nice text for a DZone article, but for a reference documentation, we should favor briefness and structure over potential nomination for Man Booker International Prize :)
> What I mean is, e.g., if someone starts with Weld, he needs steps 1., 2., 3.
> IMO, this should be in **bold** in a special chapter called "Preparing project to use Weld", with a sample code which is verified to work if copied and run, and eventually a reference to a quick-start app:
> {quote}
> There's just little one thing you need to do before you can start injecting them into stuff: you need to put them in an archive (a jar, or a Java EE module such as a war or EJB jar) that contains a special marker file: META-INF/beans.xml.
> {quote}
> In contrast, currently this most important information is buried at the end of last paragraph of irrelevantly sounding chapter, "1.1. What is a bean?". Why would anyone read "What is a bean"?
> my2p, ymmv

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira