[weld-dev] new section on beans.xml in reference documentation

[Gavin King]

OK, that's nice but there's a few problems here:

(1) Please stop bloating out Part I. I already had to move a bunch of
stuff from Part I to later in the doc. The organization of the doc is
supposed to be that we cover just the very simple basics in Part I,
leaving any more complex issues for later.

(2) The preamble for 2.3 doesn't flow from the previous section *at all*.

(3) 2.3.2 starts diving into a bunch of complex crap that the reader
doesn't know anything about at that stage in the text.

(3) I don't know where this "JAR", "EAR", "WAR" shit comes from, but
it is *not* the terminology used in the EE or CDI specs. I already
changed this stuff *back* to "jar", "ear", "war", and now I'm going to
have to do it again!

(4) Please don't forget to put <literal> around things, this was
missing in many, many places before I fixed it. Now we have a brand
new section full of un<literal>ized stuff.

(5) I spotted 2 grammatical errors with a very cursory read.

Look, I put a lot of effort and thinking into the original draft of
the refdoc and I had it at quite a professional level, even if a few
things were missing. I was extremely disappointed to come back a month
ago and discover that the whole document had decayed *significantly*
in quality, with bad writing, bad organization, new sections that
explained stuff very badly or just waffled on without any particular
point, and a few things that were just plain wrong! It took me several
more days of hard work to get the document back to the level it had
been when I handed it over.

Not Good Enough, folks.

So, starting now, please put a *lot* more thought into changes to the
refdoc. Please don't add waffle. Please don't ad badly-written stuff.
Especially, please don't fuck up my well-written stuff.

This new section belongs in Part III, after we have already introduced
interceptors, decorators and alternatives. And it needs to flow with
the rest of the text. Please don't put *anything* new in Part I, which
is already too long when balanced against the rest of the document.


On Sun, Dec 13, 2009 at 1:05 AM, Dan Allen <dan.j.allen at gmail.com> wrote:
> I just added a new section in the reference documentation on beans.xml. I
> mashed up Gavin's post on why the beans.xml is required
> (http://relation.to/13347.lace) with the documentation in the XSD for
> beans.xml
> (https://anonsvn.jboss.org/repos/weld/api/trunk/cdi/src/main/resources/beans.xsd),
> then added some filler. I've had several people ask me to expand on this
> file, and they certainly had a good point. I think it rounds out the
> documenation nicely.
>
> http://anonsvn.jboss.org/repos/weld/doc/trunk/reference/en-US/beans.xml
>
> -Dan
>
> --
> Dan Allen
> Senior Software Engineer, Red Hat | Author of Seam in Action
> Registered Linux User #231597
>
> http://mojavelinux.com
> http://mojavelinux.com/seaminaction
> http://www.google.com/profiles/dan.j.allen
>
> _______________________________________________
> weld-dev mailing list
> weld-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/weld-dev
>



-- 
Gavin King
gavin.king at gmail.com
http://in.relation.to/Bloggers/Gavin
http://hibernate.org
http://seamframework.org