Firstly, let me say, that it was a fun and interesting experience and
the athmosphere on #turbogears was really productive, hands-on and
friendly. Thanks to everybody, who helped make this happen, and thanks,
of course, to Mark Ramm for organizing it.
You're more than welcome. I'll definitely be organizing at least a
couple more of these over the next month or two. We're making good
progress, and the Docs look better and better every week, but you are
right to point out that there's still a good distance to go before we
can call it done.
- Sprints are good for producing documentation but we need to plan time
to review, organize, revise and integrate the results as well.
Karl has been looking after this, and I am very much interested in
helping out in that area as well. If we have people producing
content at a reasonable rate, we should be able to edit, organize and
integrate it as we go.
I'll also try to help by pointing people to the areas that need the
most documentation work, so that they are producing the right kind of
new content.
- Writing a new document or revising and existing one is a different
task than organizing documentation structure or proofreading. The latter
is ideal for a DocSprint while for the former one often needs more time
to think things through.
This is very true. Particularly if you are new to working on
documentation. If you've been around a while, you may very well have
some ideas already before the sprint even starts.
- While the DocSpring produced some good results, there is still a lot
to do and with the level of participation and rate of output from
yesterday we would probably need 10 more DocSprints to finish
documentation for TG 1.0
I think lots of effort needs to take place outside of the DocSprints,
and I expect that effort to happen more and more as we involve new
people in the project through aditional Doc Sprints. At the same
time, I think we're actually closer to having full 1.0 quality docs
than your 10 sprints figure would suggest.
As a result of these observations, I have the following proposals to make:
1) The TG project should consider radically opening the documentation
process:
- give write access to all pages to all registered wiki users
- install (manual?) registration review process (so that spammers are
kept out)
I don't think we should unlock everything, but I think we should
definitely grant the equivelent of SVN commit access to the Docs a bit
more liberally.
I don't think we need weekly IRC meetings, but more process discussion
on this list is a great idea, as is process/organizational page on the
wiki.
We need to work together to get more people involved in documentation,
and to provide them with positive feedback right away when they
contribute something.
I think you make some good points below, but I think we could do
better just by making the Docs list better linked to off of the Wiki
and by continuing to keep the visibility of Documentation work high on
the main wiki.
We've come a long way, and I think we can go a lot further by
intentionally bringing new people onto our team as unofficial and
organically organized as it is. ;)
-- Mark Ramm
Rationale: the current rate of documentation production and integration
is too low, we need more contributors. Currently these are kept away by
the following obstacles/annoyances:
- You can't fix obvious errors in the official pages
- It is not obvious who to contact when you want to get errors in the
docs fixed
- even if you find somebody, it takes too long until your fix implemented
- it is difficult to contribute to the work on the documentation
structure
- Apart from your name in the RecentChanges list, you get no real
recognition for your work
2) As a complementary measure or as an alternative, I propose to set up
an official "documentation team" that has regular (monthly/fortnightly?)
organizational meetings on IRC, where the following is discussed:
- status quo
- what are the next todos
- who's responsible for what
- strategic plans
3) Have a doc team page on the wiki with:
- A mission statement
- A link to the turbogears-doc mailing list
- Links to guidelines for contributing documentation, i.e. [1] and
styleguides, etc.
- Links to other resources for creating documentation:
- API docs
- SVN repo
- Tools
- Examples for good articles
- A list of who's responsible and who to contact for
- website updates
- wiki updates
- svn commits
4) Increase documentation contribution rate by offering incentments like
"article of the month" or "top documentor" awards. (free books anyone?)
What do you think? Feedback very welcome!
Chris
>
--
Mark Ramm-Christensen
email: mark at compoundthinking dot com
blog: www.compoundthinking.com/blog
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"TurboGears Docs" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/turbogears-docs?hl=en
-~----------~----~----~----~------~----~------~--~---
