Hi everybody,
so the DocSprint of yesterday is over and I'd like to thank everybody who contributed and share some observations that I took from it. 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. Here are some personal lessons: - Writing dodumentation about code takes sustantial longer than a) I thought it would and b) than writing the code itself. I started work by migrating SimpleWidgetForm for, as I thought, "warming up", but that took the best part of the day, since I had to revise it heavily. Note to self: before you start, review what's there and decide if a rewrite from scratch is quicker. - IRC is good for coordinating things but when actually writing something I should turn it off as not to distract me (likewise for email) - ReST syntax is sometimes irksome and seems to have been invented by somebody with an American keyboard (ever tried typing all these ` on a German keyboard?). I also don't like that indentation for first-level lists is significant. And here some general observations: - Guidelines for contributing docs should be announced very clearly and looked after. Examples: - I never noticed (I don't know why) that you can have an account on the doc wiki so I wrote everything as anonymous, which is a Bad Thing - Some kind soul ported SQLObjectvsSQLAlchemy from trac to moin moin but apparently nobody told him that all docs should be in ReST format (I converted it today). - Sprints are good for producing documentation but we need to plan time to review, organize, revise and integrate the results as well. - 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. - 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 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) 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 --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
