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: http://cwiki.apache.org/GMOxDOC22/what-changed-in-22.html ". 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 decisions.

thanks
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.



Reply via email to