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