[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Request for review: python-cloudfiles description

Michael Shuler wrote:
> - I would like to convey to the user what the system actually is, but I
> do not wish the descriptions to sound like buzzword-bingo advertisements
> in any way.
> - I think it would be nice to have a description that will be relatively
> portable for the various language API descriptions.
> - I would like to clarify with the list if it is necessary to include
> information to the user that they will incur usage fees, or if one could
> assume the user will go read the website, etc.
> Below are some of the possibilities we have tried and, personally, none
> hits me as, "that's perfect!"  Some suffer from sales-speak,
> awkwardness, and/or repetitiveness.. and, unfortunately, we cannot
> change the name of the storage service, which was chosen by marketing
> humans.
> I appreciate your time looking these over and helping me out.
> (original internal python module description)
> Description: Python interface to Rackspace Cloud Files
>  Cloud Files is a parallel virtualized distributed storage system.

I follow the "distributed storage system" bit, but I'm not so sure
about the "parallel virtualized" part.  Is it a virtualized DSS
that's parallel?  Or is it a DSS that's parallel-virtualized?
Would the description be clearer if it called it a "virtualized
parallel and distributed storage system", or maybe a "parallel,
virtualized, and distributed storage system"?

>  Unlike a traditional POSIX compliant filesystem, Cloud Files requires
>  that applications access storage through the use of a web services API,
>  and python-cloudfiles provides a client-side Python library for these
>  web services.

This is all very well as a description of Cloud Files, but doesn't
have much to do with Debian packages of API libraries.  I'd also
leave out the bit about POSIX.

> (ITP #543118 description - ideas from libnet-amazon-s3-perl package)
> Description: Python interface to Rackspace Cloud Files service

I like the addition of "service".  The "Python" is there in the
package name, but then again if it's the only part that varies
between the different languages we may end up recommending something
like this:

  Description: Rackspace Cloud Files service $LANGNAME interface

>  python-cloudfiles provides a simple interface to the Rackspace Cloud
>  Files service. "Cloud Files is reliable, scalable and affordable
>  web-based storage for backing up and archiving all your static
>  content". Find out more at http://www.rackspacecloud.com

It may be an advert, but at least it's in quotes; and it gives a
relatively clear idea of what the service is all about. 

>  To use this module you will need to sign up to Rackspace Cloud Files
>  and provide a "user" and "key". If you use this module, you will incurr
>  costs as specified by Rackspace. Please check the costs. If you use
>  this module with your user and key you will be responsible for these
>  costs.

This warning may be more detailed than necessary; but on the other
hand, it isn't detailed enough to make it quite clear who it is that
incurs the fee - the Python programmer or the end user running the
app?  (And then of course the "you" reading the package description
and installing the package may neither person.)

> (current package description in Python Modules Team SVN)
> Description: Python interface to Rackspace Cloud Files
>  python-cloudfiles is a Python interface to the Rackspace Cloud Files
>  storage service.  python-cloudfiles supports all of the container and
>  file object operations exposed by the Cloud Files REST API, as well as
>  methods for enabling data to be served by a public CDN.

Again some new information (or at least buzzy initialisms).  Are
these facts about supported operations also likely to be true for
Perl/Ruby versions (so the descriptions vary only in $LANGNAME)?

> (another possible description)
> Description: Python interface to Rackspace Cloud Files
>  Cloud Files is an offering from Rackspace that provides limitless data
>  storage and access over web services. This package provides the Python
>  interface needed to perform container and object operations, and CDN
>  management.
>  .
>  To use this module you will need to sign up for Cloud Files at
>  http://www.rackspacecloud.com, and accept the fees associated with
>  usage.

That has some subtly awkward bits, but on the other hand bits of it
are useful...  Okay, here's a first attempt:

  Description: Rackspace Cloud Files service $LANGNAME interface
   Cloud Files is a parallel, virtualized, distributed storage system run
   as a commercial web-based backup and archiving service. It is accessed
   via a web services API, which requires a paid account with Rackspace.
   This package provides a client-side Python module for the Cloud Files
   REST API, supporting container and file object operations as well as
   CDN management.

I hope that's not mangling it too badly.
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package

Reply to: