First version of the CakePHP 1.2 manual online
On http://tempdocs.cakephp.org/ the first version of the CakePHP 1.2 manual is online (there exists also a PDF, but I don’t know if it is the same version but it is an older version). It is a work in progress, and so some stuff is not yet documented. Anyway, it may be still useful for some of you.
I haven’t read it yet, so I can’t say anything about the content. But what I am missing is a list of those people who contributed to the manual. That’s imho much more important than a list of the members of the CakePHP team (and no, I don’t expect to show up in the docs contributor list as my only contribution to the 1.2 manual was a rejected outline).
Thank you to everyone who contributed (and still contributes) to the manual!
Update 2007-09-17: The manual is now no longer available to the public, the access is password-protected. I don’t understand this move… (thanks to David Persson for mentioning it in a comment)
Update 2007-10-23: The manual has been made publicly available at http://tempdocs.cakephp.org/.
Sorry for offtopic. Has anybody heard of Evan Sagge since April 2007? His site is down and blog is accessible only from google and archive.org caches.
Fantastic! Looks like an improved scope. Where does one provide feedback (typos, suggestions, etc.) to those writing the documentation?
@frsp: Well, you may try if you can contact him by email: evansagge(at)gmail(dot)com
@John: You may open a documentation ticket on https://trac.cakephp.org and/or join the docs related google group: http://groups.google.com/group/cakephp-docs
http://tempdocs.cakephp.org/
requires authorization now….
@ 8 UTC it didn’t…
subj
link2 for tempdocs
Well, thanks for trying Daniel ;)
The doc’s must top secret. Maybe you have to give blood in order to get access. Cake Doc’s are the new Area 51. ;)
Shame they decided to close access to it.
Hopefully will be available soon!
The tempdocs site was never intended to be public anyway. Again, this was never linked anywhere or disclosed other than in the private dev channel. It was put up so that the core developers and others working on the manual would have a chance to vet it and review it for accuracy *before* it went public. Does *that* make sense to you?
@all: Thanks for your comments!
@nate: Well, you are wrong. The link to the manual was posted by the doc leader on the public docs mailing list, so I think it was intended for the public. And as it was already public, why not leave it public? There is already a disclaimer in the manual which says “… please realize that the information provided here may be incorrect or incomplete.”
So, to me your explanation doesn’t make sense, and I have the feeling there is another reason…
No, I’m not wrong. The docs mailing list is for the docs team, the fact that it’s public is neither here nor there, and the fact remains that the site itself was not *intended* to be public…. yet.
As far as the disclaimer, I think 1.2 is a good example of people completely ignoring disclaimers. It’s alpha status has not kept anyone (ahem) from demanding complete stability. And at this point, I don’t really care if you “buy” my explanation or not. Drop it with the paranoia already, there’s no grand conspiracy. We’re doing this all for the community, remember?
@Nate,
I love watching you getting all riled up ;). I’d be willing to bet that you forgot to have your breakfast.
Your explanation is fine with me. I’m willing to wait to the “public” doc’s!
hmm ….. yeah. The documentation was closed for public access. By the way, i wrote some tutorials about CakePHP in indonesian language and it’s the first CakePHP site in “bahasa indonesia”. Just check it out at :
http://idcake.web.id/
thanks for the information, Mr. Daniel ……
@all: Thanks for your comments!
@nate: Well, whether it was intended to be public or not doesn’t matter anymore, what matters is the message you send out by this move. Anyway, it is your decision, not mine ;-)
@sunu: Thanks for the link, I added it to the resources page of this blog.
This is getting sooo boring. There are other ways to get traffic.
This is probably my fault. :/
I sent it to the docs team for review (rather than the main cakephp list). We’re giving it some spit and polish before it goes out to the public.
Sorry for the mixup.
It was me who uploaded “warez” copies of tempdocs.
I’d like to say thanks to guys working on docs and also to Daniel pointed us to “secret” url. It’s much better for me as newcomer to cakephp world to read unpolished draft for 1.2 than approximating 1.1 docs to current cake alfa. And yes, I find no sense in hiding work in progress, especially after it was published accidentally. Cakephp team should be more generous rather than wasting their time for scanning blogs for rumors and url leaks.
@ice-age: +1.
Having a manual that (you think it) is unpolished is still far more better than just googling around or guess from the 1.1 manual. So far we just have articles on the bakery, but doesn’t have a long, consolidated (even if it’s incomplete) documentation.
We all know 1.2 had changed many things from 1.1, and that many things in 1.1 doesn’t hold for 1.2 anymore - for instance, the names of the templates - it changed from .thtml to .ctp.
Yes there are discussion groups which we can use, but please also be noted that there are people who like DIY, in addition to DRY.
@ice-age: yeah, definitely, the CakePHP team should be more generous, I mean all they have been doing for SEVERAL YEARS is dedicate THOUSANDS of HOURS with absolutely NO FINANCIAL RETURN so you can make MORE MONEY by coding FASTER and BETTER. What a pack of sons of bitches…
BTW, that’s sarcasm.
@Mariano, you made me cry… Developers are proffesionals and the know why they made the CakePHP project. And certanly they didn’t made it for me.
@others… If docteam think that development of the documentation should not be public that’s ok. There is planty of documentation on the net. But… if they make it like the 1.1 manual. I don’t need it.
hi guys,
I’m new to cakephp. I’m working on a project on version 1.2.
can anyone help me to find some resources regarding the version 1.2 becuase I don’t find much resource to work in cakephp?
Any response will be appreciated.
Thanks in Advanced.
@all: Thanks for your comments!
@Mariano: Well, if it is boring for you, simply ignore it ;-)
@John: No problem :)
@ice-age, as230: I agree with you.
@Mariano: Calm down, there is no need to shout. Nobody questioned the effort the CakePHP team put into the project, but, as always, there are things which could be done better.
Oh, btw, ever heard of the Cake Development Corporation?
@Proleter: Sure, it is the doc team’s decision whether the development of the documentation should be public. But personally I think they should use a more agile approach, release early, release often.
@rupesh: Ahsan posted in his blog a list with CakePHP 1.2 resources: http://ahsanity.wordpress.com/2007/08/29/cakephp-12-the-romance-continues/
Hope that helps and good luck!
@cakebaker: yeah i’ve heard of the CDC, do you know when it got started? And eventhough CDC exists, go figure, we still dedicate countless hours to develop CakePHP…
You know what bothers me? All this people that have the “exact notion of what can be done better”, but when you ask them to join in and help out, they do so for like a week, and then they disappear…
It’s very easy to talk. But I dont see all these people that almost seem to make the complain a way of living staying up sunday 6 AM fixing bugs because someone DEMANDED they should be fixed.
Or release often.
Anyway…
CakePHP is great.
@Mariano: I know CDC was started recently. I simply mentioned it to relativize your previous statement about “with absolutely NO FINANCIAL RETURN”.
Well, if someone like me says that x could be done better, than take it as inspiration and think about it. Maybe it is something that could help the project?
They obviously don’t want help with the docs, else they would not hide their stuff until release. :D
This action seems a bit microsoft-ish: work, work, work in secret - release it with a “wow” - get tons of reports - release 10 service packs and zillion patches.
What was the benefit of opensource again? :-)
Unless they plan to sell it as a book, i don’t see why it is bad to have the draft. Can’t be worse than 1.1 .. lol (just kidding)
enough of the jokes. i respect their decision however.
Too bad i did not save the html for offline reading! Miss the docs a little since i lost the alpha pdf (which leaked way way earlier in pub-chan, btw).
I don’t see the harm in releasing alpha documentation, in the same way alpha software is released.
Did someone manage to grab a copy b4 it was password-protected. If so please share.
@all: Thanks for your comments!
@m3nt0r: I don’t know if it is planned to sell it as a book, it is possible. The PDF is still available at the link I provided in the post. And the HTML is still available in the Google Cache: http://www.google.com/search?hl=en&q=site%3Atempdocs.cakephp.org&btnG=Google+Search
@sambo: I agree with you.
@phpsc: See my answer to m3nt0r.
Add me to the chorus of voices expressing discontent at hiding documentation.
Regarding nate’s statement about people treating 1.2 as something other than alpha — my limited experience has been that the responses received in #cakephp don’t really regard 1.2 as alpha, but rather as the only release that any Cake user could hope to use effectively. Apologies if I’m misinterpreting, but I decided to roll out a new project in 1.2 just because all the answers I got seemed to presume that any serious user would have done so.
At any rate, as stated by others it would seem the point of open-source is to make the information available and disclaim any damage the user might do to herself by misinterpreting it (of course, trying to avoid misinterpretations where possible), not hide the information to protect the user from herself.
In sum it’s unfortunate that 1.2 is the version everyone tells one to use but it has no public user manual.
I’ve used cake for a year. The framework is not bad, but the docs are ugly and useless after 1-2 months.
Why do you close the docs even if you’re writing a book? Look for example symfony docs. They wrote a book, but the _whole_ material is browseable online. The stable and the development version too. It’s a little bit bizarre.
If there are enough knowledgeable people put off by this decision to hide the 1.2 manual, I suppose they could fork off the documentation project and write their own manual, right? Unfortunately I’m not anywhere near knowledgeable enough to coordinate such an effort, but at least I can throw out the idea. :)
Speaking of which…. why doesn’t someone set up an “official unofficial” CakePHP wiki for this purpose? Closing down the official wiki (as opposed to, say, restricting write access to it) seems like another dubious doc-related decision but to be fair I don’t know all the factors that entered into it.
@Philip, blerou: Thanks for your comments!
@Philip: I think the reason people use 1.2 over 1.1 is that 1.1 is a dead end. If you are lucky, there will be some bug fixes. But all new features go into 1.2. And with all those changes in 1.2 it won’t be easy to upgrade from 1.1.
@blerou: I agree with you. The new manual is not even available via repository as the 1.1 manual is.
@Philip: Sure, people could write their own manual (I don’t know if a fork would be possible as I don’t know the license of the manual).
The wiki was closed down because a lot of its content was outdated. As replacement for the wiki was the bakery thought, but it has its own problems… But feel free to start a CakePHP wiki ;-)
I also get the impression (from the google group) that Cake 1.2 is the version to use. As I’m fairly new to cake any manual for this even if it isn’t complete would be a real help. I like the idea of a wiki, the bakery doesn’t seem very comprehensive.
@Al: Thanks for your comment!
The PDF I linked in the article is still available, maybe it is helpful for you.
I’ve just built my first app in cake and am absolutely loving the framework. I’ve literally been raving about it to every developer and designer I know to give it a try.
The only thing that has been bothering me with the project is the politics of it all. I understand we all have our own agendas and everyone has an opinion (remember what your mom said about opinions?), but why oh why does it seem that this community has a constant battle between the developers of the framework and the community that uses it.
@Mariano: I truly value all of the hardwork that the cakephp developers have put in. My concern is that when you say that I shouldn’t give my suggestions for improvement because I am not going to be “hands on” in developing it myself. The truth is that it is developers like me, who are on the front lines, selling the framework to clients (mostly big media and ad agencies btw) that are going to help you get even more participation in the project.
I guess what I am trying to say is can’t we all just get along? If you think I am crazy, just go through the google group emails or search some of the cakephp blogs and you’ll see what I mean.
BTW, with every paid project I take on for CakePHP, I always plan on donating back a percentage to the cause - I highly suggest that other developers consider doing the same, its the right thing to do.
@schutzsmith: Thanks for your comment! I fully agree with you.
it is very tiring to work on a library with -really- no documentation. Mariano Iglesias, i am still working on your plug’n to make it work for 1.2. If you have a one, please let me know ;)
@serkan: Yes, I agree with you. Maybe the API helps a bit?
I am not sure Mariano reads your comment, you may have to contact him directly.
How difficult will be to upgrade existing project from 1.1 to 1.2
I am really happy to see there is so much activity in cake community right now.
In the event of cake pre-beta and temp docs goes online, as well as forming a effective user documentation strategy for my own projects.
I have made a suggestion to cake trac to ultilize some form of lightweight markup such as Markdown, reStructedText, Textile..
https://trac.cakephp.org/ticket/3457
Its really powerful as some of other software library has shown, symfony(Markdown), Django (Rest), Mootools(Markdown).
Put a readable docs in source distribution in plain text, user/developer will be happier also the software itself will be the biggest beneficiary.
There is a couple interesting example.
1. Django - put user docs in source distro is really handy when i am in middle of coding, every page/section is just a click away. no internet/compiling requried. can export to many many different formats (pdf, html, chm)
http://code.djangoproject.com/svn/django/trunk/docs/
2. Mootools - same story, but they through in a extra bit of javascript polish, a javascript markup parser. A beautiful doc pages rendered on the fly, when svn update your docs are always in sync.
http://svn.mootools.net/trunk/Docs/
What do you guys thinks? esp for those who contribute to OOS authors software library.
@sviktorov: Difficult to say, it probably depends on the complexity of your project.
To upgrade, I would setup a new Cake project and then copy your files (controllers, models, etc.) to this project and look what no longer works and fix it.
HTH
@speedmax: Thanks for your comment.
I think it is a good idea to use such a doc system. It looks to me like it is more easier to write docs using such a syntax than XML.
I didnt watch the manual until know (since I assumed it only explained the CakePHP basics which I am allready familiar with) but there is some VERY valuable stuff in there too which made me understand some things better.
Obviously it is my own fault I failed meeting a deadline as I was too busy trying to get the hang of the framework. But I couldnt help feeling a bit confused looking back when I noticed that manual allready existed (as of January 2007) when I needed it so badly.
@Tim: I am sorry to hear you missed a deadline because of that…
Like I said, I don’t blame anyone for it, and I’m very glad that the manual is now available again.