Documentation corrections

[Daniel Frey <da...@xmatrix.ch>]

Hi there,

I start to develop a feeling for merlin and I am therefore reworking through
the tutorial and documentation. Appart from the funny typos (i.e. "famework"
instead of "framework") I have also met some really confusing paragraphs
which definitively need to be enhanced.

Example: In the tutorial/creation.html file, mcconnell writes in the
subchapters 3 and 4:

001 ==================================================
002 Creating a Type Descriptor
003 --------------------------
004 
005 In order for Merlin to recognize this class as a 
006 component, we need to generate a <classname>.xinfo 
007 file.
008 
009 The following text is an example of a component 
010 type definition. It contains the declaration of 
011 the component name and the component 
012 implementation version. It was generated 
013 automatically for us by the pre-goal included in 
014 the maven.xml file. The avalon:meta plugin looks 
015 for @avalon.component tags at class level and 
016 generates component descriptors for us 
017 automatically.
018 
019 <preGoal name="java:compile">
020   <attainGoal name="avalon:meta"/>
021 </preGoal>
022 
023 ==================================================
024 Generated Type Descriptor
025 -------------------------
026 
027 <type>
028   <info>
029     <name>hello</name>
030     <version>1.0.0</version>
031     <lifestyle>transient</lifestyle>
032   </info>
033 </type>

For a first time reader, as I was some days before, this is confusing
because:
- The first paragraph (005-007) addresses the xinfo file. The code that
follows next is the preGoal, the xinfo follows in the next subchapter.
- Line 009 refers to the following text as a component definition. As a
newbie I take this serious and I am not immediately able to recognize this a
mistake. Indeed, the code in the next subchapter is the component type
definition.

I propose to 
- add the following sentences to line 007: "However, this can be done
automatically by including a pre-goal as shown below into the maven.xml
file. The avaon:meta plugin looks for @avalon.component tags at class level
and generates component the descriptors for us."
- push the paragraph (009-017) down to the next subchapter and remove the
sentences in 012-017.

I may also correct them directly if you would like to give me commit rights
to the cvs.

Cheers, Daniel


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@avalon.apache.org
For additional commands, e-mail: dev-help@avalon.apache.org

Re: Documentation corrections

[Niclas Hedhman <ni...@hedhman.org>]

On Friday 12 March 2004 22:03, Daniel Frey wrote:

<snip>Good Suggestions</snip>

> I may also correct them directly if you would like to give me commit rights
> to the cvs.

I will attend to this straight away, but it will take a while before it shows 
up on the site itself.

If you are real serious about helping out, try to make life easier by posting 
the patch, in which case you can cut down on the surrounding explainations.

Patches are most easily generated by the "cvs diff" command.
For instance;
   cvs -q diff  filename  >somename.patch

That helps a lot.

As for committer status; 
1. See page http://jakarta.apache.org/site/roles.html
2. Avalon is perhaps somewhat more lenient than many other Apache projects, 
and put more emphasis on quality than on time (some require continuing 
dedication for 6months or more)
3. Commitment towards the project is expressed in, qualified feedback, 
participation in ongoing design/coding discussions, patches, wiki updates, 
suggestions and also stuff like helping your peers. Basically anything that 
moves us forward.
4. You shouldn't feel that you are trying hard to get committer status, it 
should be fun and natural, and one day you will be asked.

Keep up the good spirit.

Niclas
-- 
+---------//-------------------+
|   http://www.bali.ac         |
|  http://niclas.hedhman.org   |
+------//----------------------+

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@avalon.apache.org
For additional commands, e-mail: dev-help@avalon.apache.org