Excellent ideas! I'll make a couple of assorted notes which you are completely free to ignore :-)
* The most helpful documentation I've used in recent years is this: http://www.google.com/search?q=python+tuple http://www.google.com/search?q=php+explode There are actually two parts to this: 1) Indexing by Google is a must. The first hit on the above searches leads you directly to the right places. 2) The styles of the documentation is quite different. The Python docs provide context, giving a good overview. The php docs are purely reference docs but have a huge amount of user-contributed code snippets. Both are valuable styles of documentation.
* Try to favor something that makes it easy for people to contribute visibly. I.e., updating a wiki site is not a visible contribution in our community. I'd rather see commit comments for the documentation so that the community is aware of new content and who contributes it.
* Shoot for a concrete near-term achievable goal, for example: Combining HelpSystem with the workspace hack that I used for the release workspaces (i.e., just compile the text as a method) and then just allow people to start writing things.
I think in this phase it's more important to get a process going than to try to perfect the tools.
Cheers, - Andreas
On 4/20/2010 10:18 PM, Casey Ransberger wrote:
Please find the attached proposal. In a workspace, do
self braceFor: #theHorror.
Seriously, though, I decided to go full-bore with the crazy ideas here. I would very much appreciate feedback of the constructively critical variety. If people really hate these ideas, I can go back to the drawing board, and come back with something folks can get behind.
To be clear: I'd rather not do it all by myself, so I will be receptive to what you have to say about it.
I am, myself, somewhat concerned that I may have erred a bit far on the side of tools; OTOH, I suspect that part of the reason mine was the only hand that went up when volunteers were called upon for the 4.0 release may have been: it was not a technically sexy release, and ours is a community of engineers. So maybe the tool ideas will go over well and get people engaged, I don't know.
Anyway, I'm dying to hear what people think!