[JBoss JIRA] Created: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.
8:30 a.m.
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
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
6:30 a.m.
New subject: [JBoss JIRA] Commented: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.
[
https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.s...
]
Pete Muir commented on WELD-900:
--------------------------------
We already have a chapter that details how to get started with Weld, called "Getting
started with Weld" --
http://docs.jboss.org/weld/reference/latest/en-US/html/gettingstarted.html
Anyway, if you have any concrete changes, please create a pull request, otherwise I'll
close this issue as it's not particularly definite about what can be changed.
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
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
6:32 a.m.
New subject: [JBoss JIRA] Closed: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.
[
https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.s...
]
Pete Muir closed WELD-900.
--------------------------
Assignee: Pete Muir
Resolution: Rejected
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
7:58 p.m.
New subject: [JBoss JIRA] Commented: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.
[
https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.s...
]
Ondrej Zizka commented on WELD-900:
-----------------------------------
May I put some notes about what I meant? Not necessarily reopening the issue.
For instance, "1.2. Getting our feet wet".
1) Call me boring, but in reference manual, I'd expect "CDI Basics" or
such.
2)
{quote}
But wait! TextTranslator does not have a constructor with no parameters! Is it still a
bean? If you remember, a class that does not have a constructor with no parameters can
still be a bean if it has a constructor annotated @Inject.
As you've guessed, the @Inject annotation has something to do with dependency
injection!
{quote}
As I wrote - such stile is fine for an article or a book.
But I'd expect a reference to be concisee. Sencences as "But wait", "Is
it still a bean?", "If you remember", "As you've guessed" and
such are just distracting. I'd rather welcome terse facts.
3) Example
{code}
@Named @RequestScoped \
public class TranslateController
{code}
If this is "Getting started" guide, then it should assume uninitiated reader.
a) @Named should eitner not be present since it's not related to the matter being
explained.
b) @RequestScoped should explained shortly - 1 sentence with a link to list of related
annotations.
I hope I explained what I meant by this jira.
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
9:24 p.m.
New subject: [JBoss JIRA] Commented: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.
[
https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.s...
]
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
8:17 a.m.
New subject: [JBoss JIRA] Commented: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.
[
https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.s...
]
Ondrej Zizka commented on WELD-900:
-----------------------------------
Errata (since I can't edit comments):
a) @Named ... explained >>, or there should be a link to an explanation<<.
"I don't think that assuming all readers are familiar with the use of
interceptors >>is appropriate.<<"
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
5:34 a.m.
New subject: [JBoss JIRA] Commented: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.
[
https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.s...
]
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
2:05 p.m.
New subject: [JBoss JIRA] Commented: (WELD-900) Docs: Improve Weld reference. Make it less poetic and more structured.
[
https://issues.jboss.org/browse/WELD-900?page=com.atlassian.jira.plugin.s...
]
Ondrej Zizka commented on WELD-900:
-----------------------------------
Okay, you know your community better, so if they like it... :)
And ok, I will create jiras for the rest.
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
4927
days inactive
4951
days old
7 comments
2 participants
participants (2)
-
Ondrej Zizka (JIRA) -
Pete Muir (JIRA)