Public Relations, Corba, Documentation, and Eggs 
Author Message
 Public Relations, Corba, Documentation, and Eggs

Okay, there isn't anything in this post about eggs. If you are reading this
just to find out the bit about eggs, you might as well stop reading now.
In fact, if you see any accidental reference to eggs, just substitute
the word spam instead. You do like spam, don't you?

First, let me say that I am a newcomer to Python. As part of my consulting
for a firm on a new product line, it became apparent that a scripting
language was needed.  After a month or so of research and consideration
I recommended Python, over Tcl, Perl, Scheme, and Lua (Java was considered,
even though it did not fit our definition of scripting language). The
choice was not made lightly, since it will affect many of the firms future
products and its customers.

I have made a personal commitment to support the PSA, as many of you
already have. I will try to get a corporate commitment from the firm
I am consulting for to directly support the PSA. It is not a large firm,
and such an expenditure would need sound (selfish) justification.

But it is hard to make any kind of pitch for python support when I find
requests for documentation on modules thrown back at me and anyone else
who asks. To be brutally honest, I think anyone who foists undocumented
code off as being "done" is a hack (not even a hacker in the old sense of
the word). Sure, we all have to start somewhere, and I see nothing wrong
with hacking together test or experimental code; but it should never see
the light of day. Alas, it seems this is precisely what the case is for
some Python modules. Some, like Tkinter, have not-quite passable docs.
This really needs to change, or Python will never achieve its potential.

If you wish to avoid a public relations disaster, I might
suggest you find more diplomatic answers to newcomers questions.
Like: "Sorry, the so-and-so who wrote that module was a double-agent
for the CIA. Maybe I can write some docs up for you in a few days."
instead of: "Maybe YOU could write the docs for that module; we are
much too important to do that. Besides, it was hard to write, so
it should be hard to understand." Otherwise, you may end up with egg on
your face.

If the Python community wishes to see its language seriously considered
for the recent OMG Corba RFP for a scripting language, it needs to follow
software engineering practices more rigorously. They'll be looking for
good documentation, among other things.

I lied about the egg part.



Sat, 27 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

(snip)

Quote:
> But it is hard to make any kind of pitch for Python support when I find
> requests for documentation on modules thrown back at me and anyone else
> who asks. To be brutally honest, I think anyone who foists undocumented
> code off as being "done" is a hack (not even a hacker in the old sense of
> the word). Sure, we all have to start somewhere, and I see nothing wrong
> with hacking together test or experimental code; but it should never see
> the light of day. Alas, it seems this is precisely what the case is for
> some Python modules. Some, like Tkinter, have not-quite passable docs.
> This really needs to change, or Python will never achieve its potential.

As for me, I realized python's "potential" when I could painlessly extend it
with tcl/tk, whereas the published perl extension of that time didn't build
on my machine.

Quote:
> If you wish to avoid a public relations disaster, I might
> suggest you find more diplomatic answers to newcomers questions.
> Like: "Sorry, the so-and-so who wrote that module was a double-agent
> for the CIA. Maybe I can write some docs up for you in a few days."
> instead of: "Maybe YOU could write the docs for that module; we are
> much too important to do that. Besides, it was hard to write, so
> it should be hard to understand." Otherwise, you may end up with egg on
> your face.

I beg your pardon?

Quote:
> If the Python community wishes to see its language seriously considered
> for the recent OMG Corba RFP for a scripting language, it needs to follow
> software engineering practices more rigorously. They'll be looking for
> good documentation, among other things.

For better or worse, I am part of the python community. If people can make
money with python they have my blessing. If they need certain coding and
documentation standards to do so, well, let them provide it.

As for myself and probably several others, I want to get something done that
I deem important but that won't be saleable. I depend on the code that
others are willing to share and I will gladly return the favor.
For me, third parties are not relevant and simply being part of the python
community "pays".

Please, don't treat the "python community" as an organization that tries to
sell its product to the highest bidder.

cjr

PS This is my last message in this thread.
--



Sat, 27 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

Quote:
> But it is hard to make any kind of pitch for Python support when I find
> requests for documentation on modules thrown back at me and anyone else
> who asks. To be brutally honest, I think anyone who foists undocumented
> code off as being "done" is a hack (not even a hacker in the old sense of
> the word). Sure, we all have to start somewhere, and I see nothing wrong
> with hacking together test or experimental code; but it should never see
> the light of day. Alas, it seems this is precisely what the case is for
> some Python modules. Some, like Tkinter, have not-quite passable docs.
> This really needs to change, or Python will never achieve its potential.

        OK, I just want to go on record as saying I have always been
incredibly impressed with the documentation for python.  I think that
is one of the major reasons I stuck with python instead of TCL -- the
documentation is so much more helpful. (And easier to find.)
        My advice is - if the lack of documentation on a particular
module bothers you that much - pretend like it doesn't exist.  I see
no reason to take it out.  In truth, I don't think I have ever come
across a *fully* documented piece of software - except of course for
reading the source.
        OK, so maybe "do it yourself" wasn't the right answer to your
request for documentation.  On the other hand if you need the answer
to that question to be "we'll get right on it" maybe you need to
purchase a commercial product.

        -Roman

----------------------------

----------------------------



Sat, 27 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

Quote:

> But it is hard to make any kind of pitch for Python support when I find
> requests for documentation on modules thrown back at me and anyone else
> who asks. To be brutally honest, I think anyone who foists undocumented
> code off as being "done" is a hack (not even a hacker in the old sense of
> the word). Sure, we all have to start somewhere, and I see nothing wrong
> with hacking together test or experimental code; but it should never see
> the light of day. Alas, it seems this is precisely what the case is for
> some Python modules. Some, like Tkinter, have not-quite passable docs.
> This really needs to change, or Python will never achieve its potential.

Documentation is always a problem and there will always be someone not
satisfied, but I can't see your point: Python is so easy to understand,
that in most cases, you don't even need any documentation.

Quote:
> If you wish to avoid a public relations disaster, I might
> suggest you find more diplomatic answers to newcomers questions.
> Like: "Sorry, the so-and-so who wrote that module was a double-agent
> for the CIA. Maybe I can write some docs up for you in a few days."
> instead of: "Maybe YOU could write the docs for that module; we are
> much too important to do that. Besides, it was hard to write, so
> it should be hard to understand." Otherwise, you may end up with egg on
> your face.

What's the point in screaming all about ?

--
Marc-Andre Lemburg        http://starship.skyport.net/~lemburg
--------------------------------------------------------------



Sat, 27 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

Quote:

> Documentation is always a problem and there will always be someone not
> satisfied, but I can't see your point: Python is so easy to understand,
> that in most cases, you don't even need any documentation.

No, it is not so easy to understand that you do not need
documentation, such a statement borders on absurdity.  You tell me if
you want to use Tkinter without docus.


Sat, 27 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

: Documentation is always a problem and there will always be someone not
: satisfied, but I can't see your point: Python is so easy to understand,
: that in most cases, you don't even need any documentation.

You mean like COBOL was meant to be? ;-)
That hardly applies to C extension modules.



Sat, 27 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

Quote:


> > Documentation is always a problem and there will always be someone not
> > satisfied, but I can't see your point: Python is so easy to understand,
> > that in most cases, you don't even need any documentation.

> No, it is not so easy to understand that you do not need
> documentation, such a statement borders on absurdity.  You tell me if
> you want to use Tkinter without docus.

I didn't say to put all docs through the shredder -- who ever
gave you that idea ???

The code is -in most cases- very well documented, the only thing
missing is a reference in TeX or HTML. Just take a look at the files
in Lib/ and you'll find that most of them (if not all) are totaly
comprehensible.

--
Marc-Andre Lemburg        http://starship.skyport.net/~lemburg
--------------------------------------------------------------



Sat, 27 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

Quote:
>If the Python community wishes to see its language seriously considered
>for the recent OMG Corba RFP for a scripting language, it needs to follow
>software engineering practices more rigorously. They'll be looking for
>good documentation, among other things.

Surely you don't expect us to meet the high standards of java
documentation?  Stuff like

  FooClass()
    this is the FooClass initializer.

Demanding! :)

Honestly the Python libs are pretty well documented, generally speaking,
by current industrial standards if you look around.  It's a far cry from,
say, the VAX/VMS standard that once existed, so we have something
to work towards, but let's be reasonable here.  Have you ever looked into
javascript?  -- Aaron Watters

===
In these colleges the professors contrive new rules and methods
of agriculture and building, and new instruments and tools for all
trades and manufactures; whereby, as they undertake, one man
shall do the work of ten: a palace may be built in a week, of
materials so durable, as to last for ever without repairing...
with innumerable other happy proposals.  The only inconvenience
is that none of these projects are yet brought to perfection;
and in the mean time the whole country lies a miserable waste;
the houses in ruins, and the people without food or cloathes:
by all of which instead of being discouraged, the are fifty times
more {*filter*}ly bent upon prosecuting their schemes; driven
equally by hope and dispair...
   from "Gulliver's travels",  (sounds vaguely familiar...)



Sat, 27 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

[snip]

Quote:

> Documentation is always a problem and there will always be someone not
> satisfied, but I can't see your point: Python is so easy to understand,
> that in most cases, you don't even need any documentation.

Hi,

I'm a python newbie, but I have a couple of comments in this regard...

I bought the "Internet Programming with Python" book, and have played
with
some of the example code. Overall, I like Python, and think it has much
promise, but here is a problem (IMO)...

Published modules need to provide some sort of interface specification
separate from the implementation.

An interface specification could be used to help automatically generate
documentation. Without a clear contract showing exactly what a module
does
the only way to figure it out is to read the code. Also, without a
contract
to adhere to, you run the risk that future versions of the module will
do
things in a different and incompatible way.

I ran into this problem using Python 1.4 with the CGI examples in the
IPWP
book. It didn't take *too* long to figure out the the genCGI (with the
book)
and the cgi module from 1.4 were not compatible. And, while it didn't
take
too long to resolve the problem, it was a little nuisance. If I had a
large
programming project with hundreds or thousands of modules, this would be
much
more than a nuisance though.

When prototyping, such a contract is not as necessary, but when building
an
engineered product that can have a long life cycle lasting through many
revisions
of the modules involved, I think it's important.

Anyway... I like Python, and hope I have an opportunity to use it in
future
projects.

Kevin



Sat, 27 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

Excerpts from ext.python: 10-Jun-97 Re: Public Relations, Corba.. Kevin

Quote:
> Published modules need to provide some sort of interface specification
> separate from the implementation.

That's why you want to write an ILU interface specification for your
Python module, whether or not you want to export it via RPC.  See
ftp://ftp.parc.xerox.com/pub/ilu/ilu.html for details.

Bill



Sun, 28 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs

Quote:
>I bought the "Internet Programming with Python" book, and have played with
>some of the example code. Overall, I like Python, and think it has much
>promise, but here is a problem (IMO)...

>Published modules need to provide some sort of interface specification
>separate from the implementation.

...

Yes this is a valid point.  I wouldn't say Python precludes this,
it just doesn't enforce it.  A good test suite for a module can at
once provide a regression test and serve as a module interface
spec (even better since it also gives example usage).  Look to

http://starship.skyport.net/crew/aaron_watters/embed/py2nsapi.py

towards the bottom where "stub classes" and a test suite are
given for the module.  Also look to

http://starship.skyport.net/crew/aaron_watters/kjbuckets/tsort.py

I think that an appropriate testing discipline (if enforced) can help
build large complex applications in Python as well as having interface
specs would (or better).  Of course Python will let you get sloppy and
not do it...

As for the cgi.py incompatibility between 1.3 and 1.4, that irked me
more than a bit, and I think it was a mistake.  Also look to the starship
site for other IPwP support, please.  - Aaron Watters
=-=
Never attribute to malice what can be explained by incompetence.



Sun, 28 Nov 1999 03:00:00 GMT  
 Public Relations, Corba, Documentation, and Eggs


Quote:
>No, it is not so easy to understand that you do not need
>documentation, such a statement borders on absurdity.  You tell me if
>you want to use Tkinter without docus.

Yes, quite right.  The inscrutable /F is addressing this
problem with tkinter.  Please see his starship pages.  - Aaron Watters
=-=
Laura buried her head in her hands.  She didn't know what
she wanted, but whatever it was, she was certain she
couldn't have it.  -Laura Ingels Wilder "Little Town on the Prairie"


Sun, 28 Nov 1999 03:00:00 GMT  
 
 [ 14 post ] 

 Relevant Pages 

1. clever lawyers, public-relations brainstorms and a giant corporation's ardor

2. clever lawyers, public-relations brainstorms and a giant corporation's ardor

3. egg on face

4. NIRCHI sucks eggs

5. easter egg?

6. Easter Egg Hunt

7. Laying an Egg

8. Decorate Easter Egg

9. Decorate Easter Egg

10. LOGO-L> Easter Egg

11. Grandmothers and eggs

12. Grandmothers and eggs

 

 
Powered by phpBB® Forum Software