<HTML><BODY>
<BR>
<BR>
On Thu, 19 Feb 2009 20:34:45 +0000, Nigel Hamilton wrote:<BR>
> > I'm not sure it'll work, but trying can't do any harm :-) I would<BR>
> > suggest, however, calling it ...::Essentials instead of ...::Gist,<BR>
> > as "gist" is a rarely-used word that won't mean anything to the<BR>
> > majority of people who don't speak English natively - and even<BR>
> > native speakers might not understand exactly what a ::Gist module<BR>
> > is meant to be and how it differs from ::Simple.<BR>
><BR>
> Good point. If one of the goals is to not make people think - then<BR>
> using a funky word may not help. On the other hand any good brand<BR>
> needs to be distinctive not descriptive ... and "Essentials" could<BR>
> be a little too descriptive ... hmm ... ideally I want it to mean<BR>
> 'extract the essential bit' ... something short and pithy that non-<BR>
> English speakers could easily understand ... tricky. I'm open to<BR>
> suggestions.<BR>
<BR>
How about Essential:: or Essence:: ? The problem with adding something<BR>
to the end is that you might conflict with the original module's<BR>
naming scheme. By contrast, starting a new top-level namespace makes<BR>
the project look more cohesive, and provides an obvious location for<BR>
the core philosophy.<BR>
<BR>
The other potential advantage that the prefix namespace affords is<BR>
that in pathological cases, you can extract multiple essences from<BR>
the same original module. I'm not sure this is necessarily a good<BR>
idea, though.<BR>
<BR>
<BR>
> > Something else to consider is that it's often poor documentation<BR>
> > that's the problem, not complicated interfaces.<BR>
><BR>
> Indeed. Template::Simple has a great interface - but unfortunately<BR>
> the documentation is a little long IMHO.<BR>
><BR>
> > And the "poor" documentation is often poor by dint of being ever-so-<BR>
> > complete and ever-so-correct without showing examples of common<BR>
> > usage.<BR>
><BR>
> Module authors are understandably keen to fully document their<BR>
> module - but this can work at odds to introducing new users to the<BR>
> problem and the module's solution.<BR>
<BR>
This is what I understood to be the main thrust of the project - to<BR>
document the essence of the module, giving a leg up to neophytes. The<BR>
cut and paste synopsis can be used directly in real code, and the rest<BR>
of the one-page POD explains why it's such a great idea. I'd like to<BR>
suggest that you could also include pointers in the POD for where to<BR>
look when the next level of sophistication is required, possibly in<BR>
sections which go beyond the one-page limit.<BR>
<BR>
If at all possible, the essence should use the same API as the<BR>
original module, even being a derived class where appropriate, making<BR>
it simple to migrate to the full-fat API.<BR>
<BR>
Here are a few more possible namespaces, modulo your prefered<BR>
capitalization scheme:<BR>
* FirstStep:: or FirstSteps::<BR>
* HowTo::<BR>
* StartWith::<BR>
<BR>
<BR>
Ooh, close match, sigmonster:<BR>
<BR>
-- <BR>
Peter Haworth pmh@edison.ioppublishing.com<BR>
"At IBM, we have no hesitation to steal or borrow other companies'<BR>
technologies ... well, we don't steal of course."<BR>
-- Bill Etherington<BR>
<BR>
<BR>
<span style="font-family:Arial; Font-size:10.0pt">
<hr width="100%">
This email (and attachments) are confidential and intended for the addressee(s) only. If you are not the intended recipient please notify the sender, delete any copies and do not take action in reliance on it. Any views expressed are the author's and do not represent those of IOP, except where specifically stated. IOP takes reasonable precautions to protect against viruses but accepts no responsibility for loss or damage arising from virus infection. For the protection of IOP's systems and staff emails are scanned automatically.”
<br><br>
Institute of Physics Registered in England under Registration No 293851 <br>
Registered Office: 76/78 Portland Place, London W1B 1NT <br>
<hr width="100%"></span>
</BODY></HTML>