HI Lyle, > Nigel Hamilton wrote: > > * POD less than one page - guaranteed > > Does this include the synopsis? This could potentially make things very > tricky. Also one page will need to be defined in rows and columns as the > size of a page depends on your resolution or windows size. >
Good points. I was going to try and take the Gist of some modules first to see what is practical. A one page synopsis is definitely too short - but I really think less is more - especially when reading web text. The Gist:: module text is more like a road sign that someone passes at high speed - it shouldn't slow you down. Ideally the visible bit at the top of the POD is enough for people to cut-and-paste and be on their way. > How about max one page synopsis and one page description? Not including > credits and links to other modules, otherwise most your page is going to > be taken up by copyright, credits and links. A cut a paste synopsis for > a complicated module like Data::FormValidator would need a couple of > examples and would again take up a lot of the page. > Yes. I think the goal would be to extract the 95% case of module usage. What do 95% of the people who use this module actually/really/truthfully use it for? What is the primary itch that this module can scratch? I think a good starting point is to look at how you use a module - would other's do the same? If so, then this is the beginning of finding the Gist of the module. > > I'm looking at doing the Gist::Email you suggested based on Email::Stuff > that I recently patched. Or would that be Gist::Email::Stuff? Is one > rule to keep the naming of the gisted module? Yes. I think the Gist name is just a pointer to the actual module. So that would be Gist::Email::Stuff. If someone never downloads the Gist module but is pointed to the real underlying module then I count that as a success. You could imagine someone searching Google for a problem (i.e., "program to send email attachments") then arriving at Gist::Email::Stuff (because the synopsis is SEOed for the problem space) but then quickly upgrading to Email::Stuff (optimised for the solution space). I don't know how this will work out in practice. But the next step is to try taking the Gist:: out of some modules and come up with a checklist (tm). NIge
_______________________________________________ BristolBathPM mailing list [email protected] http://mailman.bristolbath.org/mailman/listinfo/bristolbathpm
