Jerome,
Please accept my comments at face value--they are not criticism of
your effort, they are intended constructively to produce a more
effective document.
Immediately, I see quite a few grammatical errors that I could easily
correct if this were HTML. Sorry, I can do no more than point them
out to you so long as it's in PDF. Examples:
- "could be re-architecture" => "could be re-architectured"
- "along the V3 engineering effort." => ????
- "is build around" => "is built around".
- quite a few other grammatical errors throughout.
Clarification areas:
- "contract/service implementation paradigm." => explain (briefly)
what you mean by this. Not everyone will know.
- "A module is an encapsulated definition of reusable code" => Is it
code or is it a definition of code? Encapsulated by what? I don't
understand. Use plain English to explain your terms, not buzzwords
which themselves generate a meta-recursive demand on the reader to
understand.
- bold formal terms eg Module and Service when they are defined/
introduced. Consider adding a glossary (HTML) to which links can be
made.
- strike out useless and redundant verbage: "There is a lot of
literature around modules but to be short". That's not being "short"!
- "is a set of java classes" => how are they designated (in brief)?
- "offers services or a public API or both" => Is that "services" in
some generic meaning or Services with a specific meaning?
- "implements those public interfaces with a set of private classes."
=> *What* "public interfaces"? Are you referring to "public API"
from previous bullet?
That's through 1.1--how it reads to me. Remember, you are so
familiar with this stuff you must step back and read it from a
newbie's perspective, then clarify and rewrite until those
approaching V3 can find it easy to understand.
Lloyd
On Oct 12, 2007, at 3:00 PM, Jerome Dochez wrote:
> Hi All
>
> I have written a short document that gives an overall idea on how
> V3 is or will be architectured and gives some tips and information
> on how to work with modules and maven 2.
>
> This document will continue to evolve substantially so feedback is
> greatly appreciated.
>
> Find it in the main V3 wiki page.
>
> http://wiki.glassfish.java.net/Wiki.jsp?page=PlanForGlassFishV3
>
> Jerome
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: dev-help_at_glassfish.dev.java.net
>
---
Lloyd L Chambers
lloyd.chambers_at_sun.com
Sun Microsystems, Inc