Great stuff. I think maybe the killer app of web frameworks is good docs...
d. On 11/21/05, Aaron Trevena <[EMAIL PROTECTED]> wrote: > 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&opclick > _______________________________________________ > Maypole-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/maypole-devel > ------------------------------------------------------- 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
