Hi all, Osfamaron on #london.pm sent me some feedback about the 2.10 documentation, obviously it doesn't necessarily all apply now but there are still some useful comments that still apply.
A. ---------- Forwarded message ---------- From: Hakim Cassimally <[EMAIL PROTECTED]> Date: Nov 21, 2005 2:21 PM Subject: maypole doc comments To: [EMAIL PROTECTED] teejay, here's some comments when reading through much (not all) of Maypole docs, some may be out of date, dunno: Maypole ======= * SYNOPSIS: perhaps pointer should be to Maypole::Manual rather than to Maypole::Application, which isn't really all that useful as a synopsis? (I know the manual is mentioned in next paragraph, but on first read you often just scan short blocks like the synopsis) * DESCRIPTION: A bit rushed, though as long as you've pointed people to Maypole::Manual this may not be a problem. Details like "but this can be changed by altering configuration. (Before calling setup.)" seem out of place in DESCRIPTION text. It sounds more like a "Watch out for this!" comment for the manual or later on. * "In our example above, this is the C<BeerDB> package". The reference to BeerDB must have moved. * SEE ALSO: doesn't point to Maypole::Manual, I often skip to the SEE ALSO to look for general docs if I missed them on first scan. * AUTHOR: Says Simon Flack. Hmmm, this is 2.10 I thought that was already Teejayware? Maypole::Manual =============== * No version number * yes! I like the way that each manual chapter is precis'd here, very useful, as compared to Catalyst docs which give you a contents list so you have to search further to find out about it * Maypole::Manual::Workflow: the moment you see a sentence like "This is a technical document that describes the progress of a request through the entire Maypole system. It should be of interest chiefly to those people hacking on Maypole itself, and not to most of those who are using it" you imagine that you've come to the end of the "friendly" chapters, yet the ones afterwards are case studies for users, maybe this should go at the end? Hmmm, though skimming it, I'd say it probabky *is* important for developers using Maypole to know this stuff, so maybe just change the description? Maypole::Manual::About ====================== * No version number * Good first para * "What is Maypole?" - I don't like the way it immediately says "Presumably you have some idea of what Maypole is all about, or otherwise you wouldn't be reading this manual." Perhaps is should say "It's worth reading this section even if you have heard something about Maypole and think you know what it's about" * "I don't know if Maypole works on Windows. I'm not sure I care." grrrr. OK, I've since switched to Debuntu, but this is annoying and arrogant and will put off people from Windows backgrounds or people who are trying to sell it to Windows-centric managers. Even if someone will deploy to a Unix, they may want to develop on a company laptop running Windows. Whatever, maybe: "Maypole hasn't been thoroughly tested on Windows - we recommend using it on a Unix machine due to its advantages in our experience as a robust server and ease of installation, but if you run it on Windows, let us know!" * 'We use a link table called "handpump" to relate pubs to beers'. I'm a Brit and this confuses me. I know this is a historic example from real code, but might be worth changing to something like pubs_to_beers, just a thought. * Links: doesn't tell you which page to read next. You have to go back to Maypole::Manual to see that it's Maypole::Manual::Model. Oh, that's because perldoc renders them as the pretty text, bag of shite. Either fix perldoc or add C<> tags for these? Or just change to Next Maypole Model Classes (L<Maypole::Manual::Model>) ? Maypole::Manual::Model ====================== * No version number * =head2 Maypole::Model::CDBI s/evil/clever/ ? * Same issue with links Maypole::Manual::View ====================== * No version number * Good, I like the way that it gives some meaty TT examples rather than just referring to the TT site. * "For instance, I said we were in the middle of processing the front page": perhaps better "Let's go back to out example above" ? * "Breweries!". I did a double take here, Maypole thinks breweries are important?! This could be clarified to say that Maypole aliases the "objects" variable to the name of the table it's looking at. * Eeeek! Does Maypole do scary things with inflection of plurals? Maybe not to go into detail just here, but that could be pointed out. Aha, it's pointed out a little under =item C<plural> * =head2 Building your own view class If this should be skipped, maybe it should be moved into an appendix and referred to here? * Same issue with links Maypole::Manual::Request ======================== * Should this be called ::Cookbook ? * "B<Solution>: So far we've been using the C</table/action/id/args> form of a URL as though it was "the Maypole way"; well, there is no Maypole way. Maypole is just a framework and absolutely everything about it is overridable." I wonder if it isn't just OK to say it's *a* Maypole way, after all the TMTOWTDI thing actually puts some people off Catalyst etc. Maypole::Manual::BuySpy ======================= * First para "but ended up with something like this:". Where "this" is invisible unless you are reading HTML formatted version. hope it's any help, give me a shout if anything unclear, osfa ------------------------------------------------------- This SF.Net email is sponsored by the JBoss Inc. Get Certified Today Register for a JBoss Training Course. Free Certification Exam for All Training Attendees Through End of 2005. For more info visit: http://ads.osdn.com/?ad_idv28&alloc_id845&op=click _______________________________________________ Maypole-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/maypole-devel
