I agree with Chris' suggestion on creating tickets, but let me quickly respond here as well to see what others think...
On Jun 2, 2008, at 11:20 AM, mustan9 wrote: > > Hi, > > I have a few improvement requests for the Cake online manual. > > 1) Currently, CakePHP.org is using Google to perform searching of the > online manual. This doesn't work very well, and if you enter the value > "model" it returns lots of unrelated links outside the scope of the > manual. I would prefer that searching for "model" in the manual would > return a list of pages with that word sorted by priority. The Google search was low hanging fruit for us, so we used it. We want to make the search better, but this was an easy way to get a lot of functionality fast. I think we won't entertain enhancing it unless someone can help us out with creating the changes. I also think if you're just searching for "model," you're not going to get great search results anyway. This can be mitigated by smarter querying (ala "model associations", "model behaviors", or "supermodels"). > 2) The manual mixes tutorial sections and reference sections. It's a > little confusing. If you want to look up how to perform validation in > a model it's hidden under "4 Common Tasks With CakePHP / Data > Validation". You've separated models and validation into two > different sections of the manual. Since the model documentation is > located under "Developing with CakePHP / Models". I guess I need a community response here - we've organized it as best we can, but this is the first time this has been brought up. If I get the feeling the current outline isn't' worried, we'll change it. Thoughts, folks? > 3) "Developing with CakePHP" is really documentation for the API. It's > structured differently from other sections of the manual. For example; > All the subsections are really API objects. This really should be made > a separate manual. There should be a tutorial manual, and a reference > manual. If I need to know how to do a "findAll" with a model I look in > the reference manual, and if I need to know how to install Cake on a > shared server then I look in the tutorial manual under "Installing > Cake". The line between helping people use the API, and see the big picture tasks is really fuzzy. We don't really have any good answers here, but let me at least say that first, I don't see the advantage in splitting it up. Also, tutorials are housed in the Bakery, the manual houses a few fundamentals that are almost universally requested for (a starter tute, and an auth tute). > 4) Allow short cuts to access reference material quickly; Nothing > worse then having to browse all the subcategories of the manual to > find where you've put the documentation for "models". Do you have some specific suggestions for making this work? > 5) Add "see also" links for the reference manual. If I'm reading the > "findBy" documentation I'd like to also see a "see also; findAll" link > for anything related. Yeah, good idea (make sure that gets logged). > 6) Allow anonymous editing of the manual. Do you really need some one > to register in order to submit a fix for a spelling mistake in the > documentation? Yes. That is, unless you want to read about body enhancements, online pharmacies, and/or adult websites inside the manual. There *is* an approval process, but we want the threshold a little higher than rock bottom. > 7) Change the Table Of Contents to use AJAX so that our browsers don't > refresh every time we browse the tree. You'd need to clarify your suggestion here - I'm not sure what you mean. > 8) Package the manual as a down loadable off line resource that people > can read on the go. Such as a with a laptop while on the train headed > to work. This has been covered on the list before - search it up for some ideas on how to accomplish this. I'm also toying with the idea of offering a nice printed version of the manual as a desk reference, possibly with some extra chapters from core team guys or other wildly popular celebrities. Thanks for the input, John --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "CakePHP" 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/cake-php?hl=en -~----------~----~----~----~------~----~------~--~---
