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.
