On Thu, 19 Feb 2009 20:34:45 +0000, Nigel Hamilton wrote:
> > I'm not sure it'll work, but trying can't do any harm :-) I would
> > suggest, however, calling it ...::Essentials instead of ...::Gist,
> > as "gist" is a rarely-used word that won't mean anything to the
> > majority of people who don't speak English natively - and even
> > native speakers might not understand exactly what a ::Gist module
> > is meant to be and how it differs from ::Simple.
>
> Good point. If one of the goals is to not make people think - then
> using a funky word may not help. On the other hand any good brand
> needs to be distinctive not descriptive ... and "Essentials" could
> be a little too descriptive ... hmm ... ideally I want it to mean
> 'extract the essential bit' ... something short and pithy that non-
> English speakers could easily understand ... tricky. I'm open to
> suggestions.
How about Essential:: or Essence:: ? The problem with adding something
to the end is that you might conflict with the original module's
naming scheme. By contrast, starting a new top-level namespace makes
the project look more cohesive, and provides an obvious location for
the core philosophy.
The other potential advantage that the prefix namespace affords is
that in pathological cases, you can extract multiple essences from
the same original module. I'm not sure this is necessarily a good
idea, though.
> > Something else to consider is that it's often poor documentation
> > that's the problem, not complicated interfaces.
>
> Indeed. Template::Simple has a great interface - but unfortunately
> the documentation is a little long IMHO.
>
> > And the "poor" documentation is often poor by dint of being ever-so-
> > complete and ever-so-correct without showing examples of common
> > usage.
>
> Module authors are understandably keen to fully document their
> module - but this can work at odds to introducing new users to the
> problem and the module's solution.
This is what I understood to be the main thrust of the project - to
document the essence of the module, giving a leg up to neophytes. The
cut and paste synopsis can be used directly in real code, and the rest
of the one-page POD explains why it's such a great idea. I'd like to
suggest that you could also include pointers in the POD for where to
look when the next level of sophistication is required, possibly in
sections which go beyond the one-page limit.
If at all possible, the essence should use the same API as the
original module, even being a derived class where appropriate, making
it simple to migrate to the full-fat API.
Here are a few more possible namespaces, modulo your prefered
capitalization scheme:
* FirstStep:: or FirstSteps::
* HowTo::
* StartWith::
Ooh, close match, sigmonster:
--
Peter Haworth [email protected]
"At IBM, we have no hesitation to steal or borrow other companies'
technologies ... well, we don't steal of course."
-- Bill Etherington
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.”
Institute of Physics Registered in England under Registration No 293851
Registered Office: 76/78 Portland Place, London W1B 1NT _______________________________________________
BristolBathPM mailing list
[email protected]
http://mailman.bristolbath.org/mailman/listinfo/bristolbathpm
