geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Jencks <>
Subject Re: Documentation of new 2.2 features in current wiki?
Date Mon, 11 Aug 2008 22:53:28 GMT

On Aug 11, 2008, at 1:25 PM, bill stoddard wrote:

> 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 documentation).
> 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.
> Conclusion:
> 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.
I agree.

I'm in favor of anyone who wants to reorganize the documentation doing  
so.  I hope anyone who undertakes this will keep in mind that they  
might not be here forever and will consider ease of maintenance by  
developers and other documentation non-experts as a criterion in their  

david jencks

> Bill
> 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