What's Up, Docs?
If CakePHP is the best framework out there, why aren't the documentation efforts up to par? Ever wondered how you can help? Find out how.
Check out CakePHP's newest tool: the Cookbook.
Alright.
Word on the street is that CakePHP's documentation sucks. There: I said it.
Now, I've been at this for two years. I think we've seen some pretty big successes - both for CakePHP and it's documentation - but despite all that, there's a general feeling out in the community about how horrible the documentation is.
Rather than talk about the possible reasons or excuses why this is the case, let's talk about solutions.
We've wracked our brains as a team, and we've come up with part of the solution. We've created a new documentation application that will house the contents of the manual, community contributions, translations, and comments.
Community, meet Cookbook.
http://book.cakephp.org
Cookbook is a new application, custom made to turn bad vibes about documentation into freshly baked prose. It's wiki-like, in that you can log in and suggest a new section, or suggest edits to existing content.
It's not wiki-like in that it won't suck. We'll be reviewing each submission for style, accuracy and voice. Everyone, from the apprentice to master baker, should be able to help out. The novices among us can point out where weaknesses lie. The pros can roll up their sleeves and enlighten the masses.
Stop over and give her a look. Please realize that we're still working out kinks here and there. Feel free to suggest improvements, but I'll ask you be forgiving when she reveals her beta-ness. If you notice an issue with the application, log a ticket at http://trac.cakephp.org.
If you notice an issue with the documentation, make a suggestion via the 'book.
Finally, I'd like to close this article via open thread: How can we improve?
While you're pondering that million-dollar question, I'd ask you keep the following in mind:
Hope to hear from you all soon. I hope you realize that the lack of quality docs isn't a lack of commitment on my part. Let's all work together to take CakePHP to the next level.
Happy Baking,
John David Anderson
CakePHP Documentation
Word on the street is that CakePHP's documentation sucks. There: I said it.
Now, I've been at this for two years. I think we've seen some pretty big successes - both for CakePHP and it's documentation - but despite all that, there's a general feeling out in the community about how horrible the documentation is.
Rather than talk about the possible reasons or excuses why this is the case, let's talk about solutions.
Solution First
We've wracked our brains as a team, and we've come up with part of the solution. We've created a new documentation application that will house the contents of the manual, community contributions, translations, and comments.
Community, meet Cookbook.
http://book.cakephp.org
Cookbook is a new application, custom made to turn bad vibes about documentation into freshly baked prose. It's wiki-like, in that you can log in and suggest a new section, or suggest edits to existing content.
It's not wiki-like in that it won't suck. We'll be reviewing each submission for style, accuracy and voice. Everyone, from the apprentice to master baker, should be able to help out. The novices among us can point out where weaknesses lie. The pros can roll up their sleeves and enlighten the masses.
Stop over and give her a look. Please realize that we're still working out kinks here and there. Feel free to suggest improvements, but I'll ask you be forgiving when she reveals her beta-ness. If you notice an issue with the application, log a ticket at http://trac.cakephp.org.
If you notice an issue with the documentation, make a suggestion via the 'book.
Solution Next
Finally, I'd like to close this article via open thread: How can we improve?
While you're pondering that million-dollar question, I'd ask you keep the following in mind:
- Resources are very limited. Aside from the core team, there's only a few people I can think of who has consistently contributed to the docs effort.
- Please research the discussions on our Google Group about wikis and forums before suggesting either. It's been well visited.
- Please try to focus on positive critique rather than complaint. Let's gather some good ideas we can act on. Seeing the problem isn't as good as seeing one and offering a solution.
Hope to hear from you all soon. I hope you realize that the lack of quality docs isn't a lack of commitment on my part. Let's all work together to take CakePHP to the next level.
Happy Baking,
John David Anderson
CakePHP Documentation
thanks for bringing it up. I think what I'll do to help is document my experiences in the comments of sections. Or, maybe this isn't what you want?
Through learning and reading documention on other languages/apis, I can say my favorite thus far has been extjs docs. see http://extjs.com/learn/Tutorial:Introduction_to_Ext_2.0
One thing, off the top, that perhaps we can do better with the cake book is cross-referencing other sections.
Do we really want people just overwriting what others have done? There isn't a set style guide or anything, so I worry that voice will be disjointed.
I would also to see some kind of activity record so I can review the latest changes, see if new sections have been added, etc. That'll help when we see energy behind a section to use the momentum to carry through the documentation to completion in that area before people lose their interest.
I also would like to echo the requests to make the new documentation a more prominent link. The article was a great start and tool has a lot of promise!
An option to print or export to pdf the whole manual would be more useful.
like with
http://book.cakephp.org/complete/3/the-manual
the "All In One Page" link
As a web documentation is better for searching for topics, a printed one is much better for a sequential reading, so, it would be wellcome to make the wiki format the documentation for printing.
I think there should be some thought put into it and perhaps notify the original author that his information has been made more up to date in the cookbook and require him to review the article content before putting it back up. Perhaps even keeping the article in the archive, but new users might give up on the framework if they look to the bakery for help and find a ton of outdated information on their initial lookup.
An even easier solution, and one the community can probably take care of now, is just to Tag articles, tutorials, etc as 1.1 or 1.2.
Given that 1.1 is still the stable branch, and there may be a 1.1 user base for a while after 1.2 becomes the stable branch, this will provide value for both users.
And because we can tag articles that aren't our own, we can create the taxonomy we want to help us figure out if the solutions we find are going to work for our version.
In addition each article in the Bakery has version info in the details (at least its available for the author to set), so this also helps in that area.
Maybe after 1.2 becomes the stable branch, the 1.1 articles can be moved to its own section of the bakery as a sort of archive? Which like your original post, doesn't sound like a bad idea at all.
Nice work, I'll try to traslate some articles to Spanish.
s4lu2
We're working on it. Those'll come as other high-priority things get done (we're currently working on making translations easier).
@Rob
Yes please. :) It's not just a copy/paste job, though. The auto-generated markup at tempdocs isn't clean enough for the Book. It takes a marginal amount of re-marking up, but it's not bad.
I've already done about half of it, so we're already off to a good start.
So does this mean you want us to just start copying and pasting to and from the tempdocs to the book?
-number of edits/submissions pending review
-status of reviewed edits/submissions
may I suggest that the cake team should promote the new page even more. I can't find any link on http://cakephp.org/. Also a BIG reference on the old manual pages to the new one could help.
As for translations: Are there any german translations yet? I just don't want to start translating and learn afterwards that most of it has already been done.
There will be a language switch. In fact, we've already got Spanish and Portuguese translations being input.
I've already done half of the conversion - the reason I launched the application is because I can use the help. Please jump in and help!
Will you transpose the current tempdocs into the cookook or are we (the community) supposed to do it?
The Cookbook will house the manual, and it's translations. The manual is a structured document, where people can suggest changes and edits.
I'm not sure I see where the benefits are?