Uploaded image for project: 'Weld'
  1. Weld
  2. WELD-900

Docs: Improve Weld reference. Make it less poetic and more structured.

    Details

    • Type: Bug
    • Status: Closed (View Workflow)
    • Priority: Major
    • Resolution: Rejected
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Documentation
    • Labels:
      None

      Description

      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:

      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.

      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

        Gliffy Diagrams

          Attachments

            Issue Links

              Activity

                People

                • Assignee:
                  pmuir Pete Muir
                  Reporter:
                  ozizka Ondrej Zizka
                • Votes:
                  0 Vote for this issue
                  Watchers:
                  2 Start watching this issue

                  Dates

                  • Created:
                    Updated:
                    Resolved: