On Feb 7, 2008, at 6:17 AM, MonkeyGirl wrote:
> <snip> > find a better way of doing something and I'll update my guide to do it > that way instead." > > If I was writing official documentation, I'd feel like I was saying > "this is how it's *supposed* to be done, how it *should* be done." I > don't feel confident enough to make that claim. There's plenty of eyes that go on official docs before they go out the door. Helping the official docs effort doesn't mean we give you the keys and walk away. No one (especially at first) really has publishing power like that. It's a collaborative effort. Most people submitting docs just hand me what they have. I edit the submissions for (grammar, spelling) voice, style, etc.... but we also edit for completeness and correctness. Sometimes I'll hand it back with some suggestions, but I mostly try to iron out what I can in order to make the submission process easier. Being too new shouldn't be a problem, nor is a worry about accuracy. > If anyone else can get the documentation and code commenting to the > stage where us early adopters of CakePHP 1.2 can see what each method > of each class is doing in sufficient detail, I'm sure we can all group > together and help with the official documentation. I'd be happy to, > and it looks like others are too. Experience shows that they aren't. Experience shows that I *can't* get "someone else" to do that. It wasn't that way with 1.1, at least. Forgive me for being frank, but no one likes to help in the docs. Most people prefer to either 1: complain without helping, or 2: publish things themselves. The problem with 1 is obvious, and the problem with 2 is that we're unfocused as a community. Why are people publishing their own rather than jumping in to an official effort? It's probably some combination of these: 1. The submission process isn't clear (my fault) 2. Docs are a moving target for beta software (my fault) 3. People enjoy the credit and traffic self-published material generates 4. The docs situation is too bad to be helped (my fault), or 5. The docs situation isn't as bad as people think. I'm about ready to try the experiment of quitting, mostly to see if I'm the bottleneck. Maybe that's the problem, I don't really know. It's hard to see how I'm really doing, because I don't feel like I've ever really had an abundance of support. In two years, there's only a handful of people that have contributed multiple times (that aren't already overwhelmed with core team responsibilities). In any case, this is really like waiting to take your medicine until you feel well. Why would we need documentation if everyone "can see what each method of each class is doing in sufficient detail" ? If we're doing that, I think we're nearly done. It's rather obvious we need help *now*. :) > Is this something we can do together? I hope I'm not out of line with > these suggestions, I'm just trying to help bridge the gap between > those who are great at writing code, and those like myself who are > perhaps not so good at programming, but are still good at explaining > how things work in simpler terms. Right now I'm working on getting our new docs application online and ready for everyone. Everyone else is at Cakefest this week, so it's been hard to make decisions on things. Stay tuned, I'm working as best I can to solve these problems. I'm banking on the guess that this docs app will help out the docs process, so here's hoping. Thanks for the input, -- John --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Cake PHP" group. To post to this group, send email to cake-php@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/cake-php?hl=en -~----------~----~----~----~------~----~------~--~---
