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

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