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

[Pete Muir (JIRA)]

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

Pete Muir commented on WELD-900:
--------------------------------

{quote}
For instance, "1.2. Getting our feet wet".
1) Call me boring, but in reference manual, I'd expect "CDI Basics" or such.
{quote}

Boring :-p

Generally, I understand your comment about style, and we disagree with you, we feel the style the guide is written in is one that many people appreciate. There are other sources of info on CDI that are "bookish", such as the Java EE guide, which might be more to your taste.

Your specific comments about flow are very useful, could you open new issues for these so we can correct?




> 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