geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bill stoddard <>
Subject Re: Documentation of new 2.2 features in current wiki?
Date Mon, 11 Aug 2008 20:25:59 GMT
Been watching this conversation with interest... since the discussion 
has lagged, thought I'd throw a bit more fuel on the fire to completely 
burn down the topic. So here's what I see...

1) Developers need a 'low friction' place to document new content
The process needs to be dirt simple... go to wiki page 'foo', add page, 
add documentation to the page, done. Predictable, same process 
everytime, no need for the developers to figure out where it needs to go 
in the final doc tree (what is the final doc tree anyway), no need for 
the developer to necessarily even understand the project's overall 
documentation structure.  Developers need a place to just catch the 
essential facts, and move on.  Uncertainty of the developer about where 
to write the doc, or how to format it, or anything will increase the 
probability the developer will just conclude writing anything is just 
not worth the effort.  Lower barriers to entry... make easy for 
developers to capture their ideas, leave the organization to someone who 
likes to do that sort of work.

I've heard a couple of ideas here... Jarek suggested creating new 
content under a temp space. Joe said "I suggest that we create new 
content for 2.2 under this page for now: ".  David's 
'clearly tagging new doc with a version statement' is a variation of the 
above.  Sounds reasonable to me, and unless I misread any of the 
replies, I think this meets the developer's requirements and I don't 
think it is on conflict with Rebekah's proposal. 

2) On going maintenance of the doc
David's primary concern (which I share) is that what ever process we 
adopt for G documentation should lend itself to being maintained.  If 
all we have are developers maintaining documentation, then our doc 
structure will 'trend to' being flat and unorganized because that 
requires the least maintenance.  If all we have is developers 
maintaining the documentation, I also agree with David's conclusion that 
we should maintain a single documentation tree and tag new doc with a 
clear version statement.  However..... if I've not misread any emails,  
I think Rebekah is volunteering (with help from her colleagues)  to 
maintain the structure of our documentation, and create a new doc tree 
for each release of G (or a least when it make sense to create a new doc 
tree. The idea that she is volunteering to maintain the structure for 
the development team is the essential point... not the specific 
decisions about the exact nature of the structure of the final 

3) Documentation structure...
If Rebekah can maintain the doc structure she has proposed going forward 
while also enabling the developers to easily create new doc for new 
features, then I am a strong +1 to following her lead. 

We have someone showing up in the community to start what is essentially 
an Apache Geronimo documentation project tuned to the needs of the 
development community but offloading a lot of the 'chore' of maintaining 
the doc structure from the development community.  What's not to like 
here? .. let's make sure that the basic needs of the development 
community are met then let's get out of her way and let her contribute.

BTW, +1 for the 'single document' (infocenter? what's that?) approach.  
I strongly dislike the 'users' vs 'developers' bifurcation; the two are 
indistinguishable in the Geronimo community.


Joe Bohn wrote:
> Hi Rebekah,
> I just posted a note about a new space that I created for the 2.2 
> documentation.  The new space was really created just to get things 
> moving for 2.2.  It was not a statement of what the final structure 
> should be ... so please feel free to continue to explore this area and 
> receive comments.
> I personally haven't had a chance to consider the alternatives you 
> presented below.  However, my inclination is to keep the current 
> structure "as is" unless there are obvious problems with the 
> organization and there are resources willing to invest the time and 
> effort to change things.  Can you provide some more information on 
> what is driving the changes that you are proposing?
> Thanks,
> Joe
> wei zhang wrote:
>> Hi there,
>> This is Rebekah and I've been reading through the documentation with 
>> my colleagues for a while. I think we can keep the current version of 
>> the documentation and create another space for v2.2, because there 
>> will be users who may want to track the previous information. 
>> Regarding the organization of information, we have worked out new 
>> documentation structures based on the 2.1 info using two different 
>> appraches: one is pretty much book based, keeping some of the current 
>> look&feel; the other is info center based. If we are going to create 
>> a new space for v2.2, we can take either approach. As long as the 
>> structure is ready, people can take topics they are interested in and 
>> write up the content.
>> If you have any ideas or comments on the proposed structures, feel 
>> free to let me know. Thanks.

View raw message