Re: OpenSource documentation problems

[Mike Meyer]

Michael Ekstrand <[EMAIL PROTECTED]> writes:

> On Fri, 09 Sep 2005 18:16:36 -0400
> Mike Meyer <[EMAIL PROTECTED]> wrote:
>> You need a better browser. Mine - at least on Unix - have an option to
>> dump textareas into text files, invoke my favorite editor on them, and
>> then read the file back in when the editor exits. Assuming i'm not
>> running the browser in that editor in the first place.
>
> Which browser might this be? I am curious.

w3m has this feature. emacs-w3m uses w3m as a back end, rendering into
an emacs buffer, and gets this by default. And as I noted in the
message you quoted, there's an extension available for FireFox that
gives you the ability to invoke an external editor on the text in a
textarea.

The first browser I ever saw that did this was iBrowse. It attached a
button to each text area that invoked an external editor on the
contents of the textarea. iBrowse is my all time favorite browser. The
list of desirable features was simply amazing, and I've never seen
it's equal. The mozilla family comes close if you consider all the
extensions, but iBrowse had them built in - and still rendered faster
than a text only browser on the same platform. I doubt if I'll ever
see it's like again.

  http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Aahz]

In article <[EMAIL PROTECTED]>,
Michael Ekstrand  <[EMAIL PROTECTED]> wrote:
>On Fri, 09 Sep 2005 18:16:36 -0400
>Mike Meyer <[EMAIL PROTECTED]> wrote:
>>
>> You need a better browser. Mine - at least on Unix - have an option to
>> dump textareas into text files, invoke my favorite editor on them, and
>> then read the file back in when the editor exits. Assuming i'm not
>> running the browser in that editor in the first place.
>
>Which browser might this be? I am curious.

Lynx
-- 
Aahz ([EMAIL PROTECTED])   <*> http://www.pythoncraft.com/

The way to build large Python applications is to componentize and
loosely-couple the hell out of everything.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Michael Ekstrand]

On Fri, 09 Sep 2005 18:16:36 -0400
Mike Meyer <[EMAIL PROTECTED]> wrote:
> You need a better browser. Mine - at least on Unix - have an option to
> dump textareas into text files, invoke my favorite editor on them, and
> then read the file back in when the editor exits. Assuming i'm not
> running the browser in that editor in the first place.

Which browser might this be? I am curious.

- Michael
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Mike Meyer]

Florian Diesch <[EMAIL PROTECTED]> writes:
> A.M. Kuchling <[EMAIL PROTECTED]> wrote:
> Another problem with Wikis is that you have to be online to use them and
> can't use your favourite editor to write.

You need a better browser. Mine - at least on Unix - have an option to
dump textareas into text files, invoke my favorite editor on them, and
then read the file back in when the editor exits. Assuming i'm not
running the browser in that editor in the first place.

If you're using a mozilla derivate, there are a couple of extensions
to give you this functionality. MozEx appears to be DOA, but may work
for you anyway. viewsourcewith works in a recent version of FireFox,
though. TextAreaTools looks promising, but it's more an editor in and
of itself than a way to ship text out to your favorite editor.

> At least for me email is the best medium to report bugs.

Which leaves me using the same editor as my browser does...

http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
-- 
http://mail.python.org/mailman/listinfo/python-list

Improving Python docs (was Re: OpenSource documentation problems)

[Aahz]

In article <[EMAIL PROTECTED]>,
Steve Holden  <[EMAIL PROTECTED]> wrote:
>Aahz wrote:
>> In article <[EMAIL PROTECTED]>,
>> Steve Holden  <[EMAIL PROTECTED]> wrote:
>.> 
>>>Bear in mind that the PSF made its very first grants last year. The 
>>>reason none of those grants was awarded to a documentation project was 
>>>that the (volunteer) Grants Committee and helpers didn't see any 
>>>documentation projects worthy of support. 
>> 
>> Really?  And what exactly is "Software Engineering with Python for
>> Scientist and Engineers" if not a documentation project?  It may not be
>> the kind of documentation people are talking about in this thread, but it
>> certainly is documentation.
>
>Sigh. Fine. Any more nits you'd like to pick?

  Why are you calling this a nit?  It is direct proof that
the PSF is prepared to allocate financial resources to improve the Python
documentation.  We only await people to take up the challenge.
-- 
Aahz ([EMAIL PROTECTED])   <*> http://www.pythoncraft.com/

The way to build large Python applications is to componentize and
loosely-couple the hell out of everything.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Roel Schroeven]

Adriaan Renting wrote:

> In my Windows days I realy liked the Borland documentation, it was 
> way better as the Visual Studio/MSDev docs. Borland C++Builder used 
> to come with a complete rewrite of the Win32 API docs, next to the 
> docs of it's own API.

Yes, but the two are completely separate. If you press F1 on a
misspelled function, it doesn't find the function in its Win32 section
and opens its Borland section, even though it's not there either. You
have to manually open the Win32 help in that case if that's what you
need (e.g. if you don't know the exact name of the function you're
looking for). And I think MSDN is more detailed; I almost always use
MSDN instead of Builder's builtin Win32 help. I also think that 
Borland's documentation on general (e.g. STL) and Borland-specific (e.g. 
__property) C++-language topics isn't as good as it should and could be.

> One of the things I realy liked about C++Builder, and haven't found
> anywhere else*, is that if you push F1 anywhere in your code, it will
> pop up the help of whatever object/class/function/lib your cursor is
> sitting on.

I've been doing that in Visual Studio since the first version I used, 
which was 5 IIRC.

> No need to hunt google or some awkward CD search, just
> press F1 when you don't remember exactly how to call
> SetModemParams(). (*I'm not current with the latest MS and Borland
> offerings)

What I've always done with MSDN: copy the whole thing from CD to HD, and 
do a minimal install from there. Then the help application can find 
everything without asking for the CDs.


-- 
If I have been able to see further, it was only because I stood
on the shoulders of giants.  -- Isaac Newton

Roel Schroeven
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Adriaan Renting]

>>>Terry Hancock <[EMAIL PROTECTED]> 08/31/05 11:59 pm >>> 
|> >I have NEVER seen a closed source application or programming 
|> >language that came with that much documentation and support. 
|> 
|>I'm no fan of Microsoft, but in general, the Win32 API is far 
|>better documented than is Python. (Just don't use the searching 
|>facilities on the MSDev CD's to find the doc; Google it up.) 
| 
|Okay, I was being a little bit tricky here, too.  I said I'd 
|*never seen* better documentation on a closed source application. 
|It's unclear to me whether that means it doesn't exist, or I just 
|can't get hold of it, because it's closed source code. 

In my Windows days I realy liked the Borland documentation, it was way better 
as the Visual Studio/MSDev docs. Borland C++Builder used to come with a 
complete rewrite of the Win32 API docs, next to the docs of it's own API. One 
of the things I realy liked about C++Builder, and haven't found anywhere else*, 
is that if you push F1 anywhere in your code, it will pop up the help of 
whatever object/class/function/lib your cursor is sitting on. No need to hunt 
google or some awkward CD search, just press F1 when you don't remember exactly 
how to call SetModemParams().
(*I'm not current with the latest MS and Borland offerings)

I still hope Novell will be able to get borland to revive Kylix.

I still think the Python docs aren't realy bad, they could benefit from the 
addition of a functionality based index like Qt has, like in 
qt3/doc/html/groups.html. Qt's docs are quite good I think, although I don't 
have a lot of experience with them yet, I have been able to find what I needed.

Some of my colleagues are quite enthousiastic about Root's documentation: 
http://root.cern.ch/root/doc/RootDoc.html.


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Steve Holden]

Aahz wrote:
> In article <[EMAIL PROTECTED]>,
> Steve Holden  <[EMAIL PROTECTED]> wrote:
> 
>>Bear in mind that the PSF made its very first grants last year. The 
>>reason none of those grants was awarded to a documentation project was 
>>that the (volunteer) Grants Committee and helpers didn't see any 
>>documentation projects worthy of support. 
> 
> 
> Really?  And what exactly is "Software Engineering with Python for
> Scientist and Engineers" if not a documentation project?  It may not be
> the kind of documentation people are talking about in this thread, but it
> certainly is documentation.

Sigh. Fine. Any more nits you'd like to pick?

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC http://www.holdenweb.com/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Aahz]

In article <[EMAIL PROTECTED]>,
Steve Holden  <[EMAIL PROTECTED]> wrote:
>
>Bear in mind that the PSF made its very first grants last year. The 
>reason none of those grants was awarded to a documentation project was 
>that the (volunteer) Grants Committee and helpers didn't see any 
>documentation projects worthy of support. 

Really?  And what exactly is "Software Engineering with Python for
Scientist and Engineers" if not a documentation project?  It may not be
the kind of documentation people are talking about in this thread, but it
certainly is documentation.
-- 
Aahz ([EMAIL PROTECTED])   <*> http://www.pythoncraft.com/

The way to build large Python applications is to componentize and
loosely-couple the hell out of everything.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Paul Rubin]

Steve Holden <[EMAIL PROTECTED]> writes:
> > legitimate.  Python's core developers are in a leadership position for
> > Python whether they like it or not; and users and volunteers absorb
> > the attitudes of the leaders.
> 
> So, what you are saying is because the developers (I explain in
> another post on this thread that I'm not a developer, but I *am* a
> director for the PSF), having taken the time and trouble to produce
> something that you (for want of a better example) find incredibly
> useful, are now beholden to improve it still further and make it still
> more useful, because otherwise nobody else will feel it necessary to
> create and maintain documentation of high quality?

The developers are not beholden to anyone for anything, but if they
also act as Python advocates and claiming that Python is good or
well-documented software, they're the ones responsible for backing up
the claims.  If they want to say that it's experimental/unreliable or
poorly documented, their responsibility is much lower.  But they
promote it as being suitable for critical applications.

> Bear in mind that the PSF made its very first grants last year.

OK, I thought it had been doing stuff like that for longer.  My error.

> The reason none of those grants was awarded to a documentation
> project was that the (volunteer) Grants Committee and helpers didn't
> see any documentation projects worthy of support.

It looks to me like the approach of calling for random proposals
doesn't get the right kind of proposals.  The PSF should instead make
its own list of stuff it wants done, and call for people to step
forward to do those things.  Or if there's enough funds, it should
hire some full time people and assign tasks to them.

> What Python really needs is for Python enthusiasts to understand that
> the future of the language is largely in their hands. It's easy to say
> "but I can't do this" or "I can't do that". Forget such
> negativity. Find something you *can* do to improve Python - document a
> module, chair a conference, or (as *you* already do) contribute your
> knowledge and experience to c.l.py to improve the level of Python
> awareness.

No, that's completely wrong; most of the suggestions I've made to
improve Python cannot be made by "outsiders".  I can't add modules to
the stdlib that I think belong there.  Only the core developers can do
that.  I can't add conditional expressions to the language to stop
clpy newbies from asking for them practically every other week.  Only
the BDFL can do that.  I can't phone up John Shipman and ask him on
behalf of the PSF if he'll re-license his tkinter manual so Python can
include it, because only the PSF can do that.  You get the idea.

Anyway, I don't want to be a Python developer or Python volunteer.
I'm just a user.  I do volunteer work on other projects that don't
happen to be Python.  If I had more time or energy available to do
more volunteer work, I'd still put it in those other projects and not
in Python.  Python for me is a tool, like a hammer.  If the hammers I
use keep breaking or hitting the nails the wrong way, I might contact
the manufacturer and urge various improvements, but I'm not interested
in their suggestions that I come work on improving the hammers myself.
I want to build houses, not make hammers.  I'm not bashing Python and
I'm happy to be a user, but my volunteering priorities are elsewhere.

> I have done all of these things, and I firmly believe that each could
> have been done better. Unfortunately those with superior skills chose
> not to engage the Python community. Which left it stuck with me. Poor
> Python.

I don't know that my skills are so superior, but I believe I'm
engaging the Python community.

> Most of all, realise that there is no "us" and "them". *We* are
> "them", and it's up to *us* to accept that and try to improve things.

"We" (i.e. "you") is not "me" except on an incidental basis.  See above.

> Please understand that I don't mean to belittle anyone who has made
> any kind of contribution to Python (even Xah Lee has his place, though
> I tremble to think so). I just want more Python users to understand
> that there are many contributions they could make that are well within
> their capabilities, and to get off their butts and start doing
> something!

Thanks for the pep talk but you're not telling me anything I don't
already know.  Really, I like your posts and appreciate the work
you've done, but that particular line of advice comes across as
patronizing.  I know what projects I want to allocate my volunteer
development time to and Python isn't one of them.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Paul Rubin]

[EMAIL PROTECTED] writes:
> Also, "not that long ago" must mean different things for different people.
> I think we've required logins for three years or more.

I hope you're not right and that it hasn't really been that long.
Yikes ;-).
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[skip]

Tim> [Paul Rubin]
>> Until not that long ago, it was possible to submit sf bugs without
>> being logged into sf.  Why did that change?

Tim> To reduce tracker spam, to reduce tracker vandalism, and to make it
Tim> possible to contact submitters when needed.

Also, "not that long ago" must mean different things for different people.
I think we've required logins for three years or more.

Skip
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Peter Hansen]

A.M. Kuchling wrote:
> On Fri, 02 Sep 2005 06:19:16 GMT, 
>   Dennis Lee Bieber <[EMAIL PROTECTED]> wrote:
> 
>>  My attempts at simple came in closer to the life insurance than
>>Lincoln -- forget about Hemingway; the only way I could approach his
>>writing was to stick to: Hello World; Good day; See you later; Bye.
> 
> 
> A quote I like:
> 
>   I like long and unusual words, and anybody who does not share my tastes is
>   not compelled to read me. Policemen and politicians are under some
>   obligation to make themselves comprehensible to the intellectually
>   stunted, but not I. Let my prose be tenebrous and rebarbative; let my
>   pennyworth of thought be muffled in gorgeous habilements; lovers of Basic
>   English will look to me in vain. 
> -- Robertson Davies, _Marchbanks' Garland_

Hmmm... So Robertson Davies programmed in Perl? ;-)

-Peter
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Tim Peters]

[Paul Rubin]
> Until not that long ago, it was possible to submit sf bugs without
> being logged into sf.  Why did that change?

To reduce tracker spam, to reduce tracker vandalism, and to make it
possible to contact submitters when needed.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[A.M. Kuchling]

On Fri, 2 Sep 2005 01:28:22 -0500, 
Terry Hancock <[EMAIL PROTECTED]> wrote:
> Hmm. Still sounds like "there ought to be a wiki".  I've seen references
> to two different ones on this thread. One was then debunked as a "failed
> experiment".  The other just gave me a DNS lookup failure (maybe the
> URL was wrong).

The Python wiki is at ; I didn't see the
earlier posting and don't know if it gave the right URL or not.

--amk
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[A.M. Kuchling]

On Thu, 1 Sep 2005 23:08:18 -0400, 
Fred L. Drake, Jr. <[EMAIL PROTECTED]> wrote:
> Ideally, emails to docs at python.org would result in issues being created 
> somewhere, simply so they don't get lost.  It probably doesn't make sense for 
> those to land in SourceForge automatically, since then everyone has to read 
> every plea for a printable version of the documents.

As a stop-gap, could we encourage people to record issues on a wiki page?
Then someone could periodically look at the page and act on the suggestions
there.

The problem is that Wikis aren't really newbie-friendly, either; while you
don't need to register for the Python wiki any more, many people don't
realize the pages are editable.  Still, it might be worth a try.

--amk
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[A.M. Kuchling]

On Fri, 02 Sep 2005 06:19:16 GMT, 
Dennis Lee Bieber <[EMAIL PROTECTED]> wrote:
>   My attempts at simple came in closer to the life insurance than
> Lincoln -- forget about Hemingway; the only way I could approach his
> writing was to stick to: Hello World; Good day; See you later; Bye.

A quote I like:

  I like long and unusual words, and anybody who does not share my tastes is
  not compelled to read me. Policemen and politicians are under some
  obligation to make themselves comprehensible to the intellectually
  stunted, but not I. Let my prose be tenebrous and rebarbative; let my
  pennyworth of thought be muffled in gorgeous habilements; lovers of Basic
  English will look to me in vain. 
-- Robertson Davies, _Marchbanks' Garland_

--amk
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Michael Sparks]

Paul Rubin wrote:

> Michael Sparks <[EMAIL PROTECTED]> writes:
>> > I've submitted a number of doc bugs to sourceforge and the ones
>> > that are simple errors and omissions do get fixed.
>> 
>> Cool.
> 
> Better than nothing, but it's only one class of problem, and maybe the
> easiest kind to report.

[lots and lots of stuff snipped]

All very interesting, and will take me a while to digest. I must admit I
find the whole set of suggestions/observations taken together to be
very interesting/useful and I'll try and take them on board with my own
projects first.

Many thanks for the detailed response, it's very much appreciated.

Regards,


Michael.
-- 
[EMAIL PROTECTED], http://kamaelia.sourceforge.net/
British Broadcasting Corporation, Research and Development
Kingswood Warren, Surrey KT20 6NP

This message (and any attachments) may contain personal views
which are not the views of the BBC unless specifically stated.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Paul Rubin]

Michael Sparks <[EMAIL PROTECTED]> writes:
> > I've submitted a number of doc bugs to sourceforge and the ones that
> > are simple errors and omissions do get fixed.  
> 
> Cool. 

Better than nothing, but it's only one class of problem, and maybe the
easiest kind to report.  

There's another type of doc problem though, which is when the doc
simply doesn't explain how to use something.  It's not easy to submit
a bug report that says more than "this doc is no good".  Example: I
want to scrape a web page with urllib2 that involves logging into a
site, then going to the page I want to scrape and presenting a cookie
that came from the login page.  OK, urllib2 recently got a feature
for that, thanks to John J. Lee:

   http://www.python.org/doc/2.4.1/lib/http-cookie-processor.html

But reading that page, or the parent page for urllib2 itself, how the
heck am I supposed to use the feature?  Answering that would probably
take an hour or two of pondering the source code.  I found another way
to solve my problem instead.  And without spending that pondering
time, I can't submit a better bug report than "this doc page doesn't
explain how to use the feature".

I think PHP's online doc system is way superior for this kind of issue
since it's easy to post questions about the doc page directly to the
page, and for other people to answer.  Later, the doc editors can read
over the comments and merge the good info from them into the doc
source.

> OK, it's not the best solution in the world I'll agree, but my point was in
> general very few people like writing docs even when paid, let alone when
> not. As a result it's not that suprising IMO that if paid you end up with
> more docs. 

I think people like doing good work whether they're paid or not
(assuming it's work that they want to do at all).  Therefore, if
someone goes in with the view that software isn't good unless it's
well-documented, then good documentation will result.  So, GNU has
good docs because RMS was very emphatic about that view and got other
people involved in the project to share the view.  See for example:

http://www.gnu.org/software/emacs/manual/html_node/Bug-Criteria.html

"If after careful rereading of the manual you still do not understand
what the command should do, that indicates a bug in the manual, which
you should report. The manual's job is to make everything clear to
people who are not Emacs experts--including you. It is just as
important to report documentation bugs as program bugs.

"If the on-line documentation string of a function or variable
disagrees with the manual, one of them must be wrong; that is a bug."

With Python the docs seem like much more of an afterthought.

> > I usually do report doc bugs, but my frustration (and I think Bryan's)
> > is that there are so many bugs in the first place.  It means that the
> > authors are not applying high enough quality standards to their own
> > work before releasing it.  That applies to Python's code as well as
> > its docs.  It's not crap,
> 
> Or maybe they're just doing their best? 

I don't think so.  How could you consider that example above about the
http cookie processor class to be an example of someone doing their
best?  The feature is mentioned tantalizingly but there's flat-out
zero description of how to use it.  Good documentation was simply not
a priority when that patch got added.

Another example from last week (now fixed): the shelve module doc
didn't mention the sync() operation without which there's no way to
flush updates to disc.  One thing I remember about RMS preparing Emacs
releases is whenever he did one, he'd go over the code change log
starting from the previous release, and make sure that every code
change had a corresponding doc update if it needed one.  From the
number of little doc ommissions I see like the shelve.sync operation
(maybe not that specific one), it's pretty clear to me that nobody is
doing anything like that cross-checking for Python releases.

> It might seem silly but when I do write docs, personally it takes me
> around 4-10 times longer to write the same number of lines as
> documentation than as code, whilst trying to maintain a similar
> quality. I think thats on a good day.

Well, docs have more characters per line than code, so that ratio
isn't surprising.  On the other hand, docs usually don't need
intricate design or debugging the way code does.  I could usually slog
out docs while too tired to code accurately.  Another RMS doc recipe
was: after writing each sentence, re-read it and ask yourself what
someone reading that sentence will want to know next.  That tells you
what the next sentence should be.  Following that formula til
everything was covered, printing out the result and circulating it to
a few people for review, and incorporating the comments, generally
resulted in a usable doc.

The main difference between writing code and docs that maybe bothers
programmers is that docs don't interact with yo

Re: OpenSource documentation problems

[Terry Hancock]

On Thursday 01 September 2005 10:11 pm, Paul Rubin wrote:
> "Fred L. Drake, Jr." <[EMAIL PROTECTED]> writes:
> > Ideally, emails to docs at python.org would result in issues being
> > created somewhere, simply so they don't get lost.  It probably
> > doesn't make sense for those to land in SourceForge automatically,
> > since then everyone has to read every plea for a printable version
> > of the documents.
> 
> Until not that long ago, it was possible to submit sf bugs without
> being logged into sf.  Why did that change?  What was the problem with
> non-logged-in bug reports?  I submitted some number of them just
> because I couldn't be bothered logging in, and they got handled like
> any other bug reports.  

Hmm. Still sounds like "there ought to be a wiki".  I've seen references
to two different ones on this thread. One was then debunked as a "failed
experiment".  The other just gave me a DNS lookup failure (maybe the
URL was wrong).

If there is one, or if one is established, then some work would
need to be done to direct people to it from the existing documentation.
The main issue to be resolved would be establishing which wiki
Mr. Drake is going to read, I suppose. ;-)

Of course, I have a SF account, so I could use the existing system.
But in the interest of reducing obstacles to contribution it would
seem like a good idea. I've only ever set up ZWiki, though, and I
don't seem to completely understand it, as I keep having permissions
problems with it. But I know there are serious wiki people on this
list.

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Terry Hancock]

On Thursday 01 September 2005 04:03 am, Fredrik Lundh wrote:
> Steve Holden wrote:
> > I agree that maintaining documentation is a generic problem of the open
> > source world, but it's a sad fact of life that generally people are
> > better-motivated to complain about documentation (and almost everything
> > else) than to help improve it.
> 
> another problem is that to be able to do really good work on the
> documentation, you need to know things well enough to "have the
> big picture".  and once you have that, you'll find that the docs aren't
> really as bad as you once thought they were.

Or "Once you understand the problem well enought to explain it to
someone, it suddenly seems a lot less urgent to do so."  That's kind
of a viscious circle, isn't it?

Honestly, I wouldn't mind helping out with documentation myself, as
I'm pretty confident I could do fairly good work (though I doubt I
would ever please XL), but I just haven't found anything that bothered
me about Python's existing documentation.  Maybe I should look harder.

I do notice that we seem to have "learning styles" issues. The one
thing I've gathered from Xah Lee's execrable posts is that he learns
exclusively by studying examples, and gets nothing from descriptive
text. I'm almost exactly the opposite -- when I go to the documentation,
I'm looking for "the big picture" as you say. 

I have loads of example code to check for exact usage.  And after a
couple of weeks with Python, I stopped finding the library modules'
approach to things at all surprising. I generally could guess the
correct behavior and test it right away (I have been really surprised
at the number of times I just took a wild guess at what a method would
be called, and turned out to be right).

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Steve Holden]

Fred L. Drake, Jr. wrote:
> On Thursday 01 September 2005 22:53, Steve Holden wrote:
>  > So, probably the best outcome of this current dialogue would be a change
>  > to the bottom-of-page comment so instead of saying
>  >
>  > """Release 2.4, documentation updated on 29 November 2004.
>  > See About this document... for information on suggesting changes. """
>  >
>  > it said
>  >
>  > """Release 2.4, documentation updated on 29 November 2004.
>  > See About this document... for information on suggesting changes, or
>  > mail your suggestions to [EMAIL PROTECTED]"""
> 
> The reason I changed the text there and on the "About..." page was to avoid 
> it 
> all coming to the doc team (of one) as email, where it too often was lost 
> whenever I was swamped by whatever work projects I was involved in at the 
> time.  That's a big reason to continue to emphasize using SourceForge instead 
> of my mailbox.
> 
> Ideally, emails to docs at python.org would result in issues being created 
> somewhere, simply so they don't get lost.  It probably doesn't make sense for 
> those to land in SourceForge automatically, since then everyone has to read 
> every plea for a printable version of the documents.
> 
> At one time, there was hope that we could get a Roundup tracker running for 
> the webmaster address, to help make sure that each request received an 
> appropriate response, and I secretly hoped to point the docs address at that 
> as well.  Unfortunately, not enough time was available from people with 
> sufficient Roundup know-how to finish that effort.  I still think that would 
> be really nice.
> 
> 
>   -Fred
> 
I suspected as as much, but I'm glad of your confirmation. Symptomatic 
that nobody else on this thread bothered to Cc docs at python dot org to 
see what "the team" (all one of you) had to say about it.

Given that my suggestion was nixed for good reason, my fallback position 
is that you need help on the documentation, and also on a subsystem to 
channel comments effectively into issues that can be followed up, by 
whatever means available, and by more than one person. Maybe we should 
work on that.

In the meantime thanks for your hard work on the docs, which is IMHO 
insufficiently appreciated.

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC http://www.holdenweb.com/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Steve Holden]

Paul Rubin wrote:
[snip snippety snip snip, snip snip]
> 
> Calling the Python docs "worthless" is false and unconstructive;
> saying that the docs have shortcomings in part because the Python
> project itself places too little priority on doc quality is perfectly
> legitimate.  Python's core developers are in a leadership position for
> Python whether they like it or not; and users and volunteers absorb
> the attitudes of the leaders.

So, what you are saying is because the developers (I explain in another 
post on this thread that I'm not a developer, but I *am* a director for 
the PSF), having taken the time and trouble to produce something that 
you (for want of a better example) find incredibly useful, are now 
beholden to improve it still further and make it still more useful, 
because otherwise nobody else will feel it necessary to create and 
maintain documentation of high quality?

>  The PSF and the FSF both sometimes fund
> people to do coding projects.  Why does the PSF (apparently) not fund
> anyone to do doc projects, like the FSF does?  I would say this shows
> the PSF's priorities are screwed up.  Documentation is every bit as
> important as code.
> 
Bear in mind that the PSF made its very first grants last year. The 
reason none of those grants was awarded to a documentation project was 
that the (volunteer) Grants Committee and helpers didn't see any 
documentation projects worthy of support. I'm not actually sure they saw 
any documentation proposals at all. So they chose to support the 
development of new teaching materials (hey, that might be 
documentation), an update to Jython and an improved SNMP implementation.

I guess your proposal must have been lost in the mail ;-)

What Python really needs is for Python enthusiasts to understand that 
the future of the language is largely in their hands. It's easy to say 
"but I can't do this" or "I can't do that". Forget such negativity. Find 
something you *can* do to improve Python - document a module, chair a 
conference, or (as *you* already do) contribute your knowledge and 
experience to c.l.py to improve the level of Python awareness.

I have done all of these things, and I firmly believe that each could 
have been done better. Unfortunately those with superior skills chose 
not to engage the Python community. Which left it stuck with me. Poor 
Python.

Most of all, realise that there is no "us" and "them". *We* are "them", 
and it's up to *us* to accept that and try to improve things.

Please understand that I don't mean to belittle anyone who has made any 
kind of contribution to Python (even Xah Lee has his place, though I 
tremble to think so). I just want more Python users to understand that 
there are many contributions they could make that are well within their 
capabilities, and to get off their butts and start doing something!

existential-ly y'rs  - steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC http://www.holdenweb.com/
Holden Web Ltd

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Paul Rubin]

"Fred L. Drake, Jr." <[EMAIL PROTECTED]> writes:
> Ideally, emails to docs at python.org would result in issues being
> created somewhere, simply so they don't get lost.  It probably
> doesn't make sense for those to land in SourceForge automatically,
> since then everyone has to read every plea for a printable version
> of the documents.

Until not that long ago, it was possible to submit sf bugs without
being logged into sf.  Why did that change?  What was the problem with
non-logged-in bug reports?  I submitted some number of them just
because I couldn't be bothered logging in, and they got handled like
any other bug reports.  
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Fred L. Drake, Jr.]

On Thursday 01 September 2005 22:53, Steve Holden wrote:
 > So, probably the best outcome of this current dialogue would be a change
 > to the bottom-of-page comment so instead of saying
 >
 > """Release 2.4, documentation updated on 29 November 2004.
 > See About this document... for information on suggesting changes. """
 >
 > it said
 >
 > """Release 2.4, documentation updated on 29 November 2004.
 > See About this document... for information on suggesting changes, or
 > mail your suggestions to [EMAIL PROTECTED]"""

The reason I changed the text there and on the "About..." page was to avoid it 
all coming to the doc team (of one) as email, where it too often was lost 
whenever I was swamped by whatever work projects I was involved in at the 
time.  That's a big reason to continue to emphasize using SourceForge instead 
of my mailbox.

Ideally, emails to docs at python.org would result in issues being created 
somewhere, simply so they don't get lost.  It probably doesn't make sense for 
those to land in SourceForge automatically, since then everyone has to read 
every plea for a printable version of the documents.

At one time, there was hope that we could get a Roundup tracker running for 
the webmaster address, to help make sure that each request received an 
appropriate response, and I secretly hoped to point the docs address at that 
as well.  Unfortunately, not enough time was available from people with 
sufficient Roundup know-how to finish that effort.  I still think that would 
be really nice.


  -Fred

-- 
Fred L. Drake, Jr.  
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Steve Holden]

Fredrik Lundh wrote:
> Rocco Moretti wrote:
> 
> 
>>Something a simple as allowing doc bugs to be submitted from a webform
>>w/o login would reduce the barrier to contribute. - Increasing the size
>>of the "About" text wouldn't hurt either. (To be honest, I've never
>>noticed that text before, and it never occurred to me look at the
>>"About" page for information on error reports.)
> 
> 
> the useredit approach I'm using over at the librarybook site works
> pretty well.  for example, if you go to
> 
> http://effbot.org/librarybook/mailbox.htm
> 
> and click "suggest changes" at the bottom, you can edit the page
> source, preview the changes, and generate a patch when you're
> done, all without signing up or logging in.
> 
> (unfortunately, Python's documentation is written in LaTeX, using
> a rather advanced tool chain to get from sources to HTML, so the
> librarybook approach won't really work "out of the box")
> 
That's true, but (as I mentioned a few minutes ago in another post) the 
docs team will happily accept plain text of that's all the contributor 
can provide. It's *that* fact that needs to become more obvious.

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC http://www.holdenweb.com/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Steve Holden]

Rocco Moretti wrote:
> Steve Holden wrote:
> 
> 
>>Every page of the docs links to "About this document", which contains 
>>the following: """If you are able to provide suggested text, either to 
>>replace existing incorrect or unclear material, or additional text to 
>>supplement what's already available, we'd appreciate the contribution. 
>>There's no need to worry about text markup; our documentation team will 
>>gladly take care of that."""
> 
> 
> There is just one giant roadblock to that suggestion - Sourceforge 
> requires a login to post bugs/patches.
> 
Well OK, I have to descend to observations based on personal experience 
here, but way back when I was a Python noob and I had a suggestion about 
how the docs might be [slightly] improved I just actioned the first 
sentence in the paragraph from which I extracted my previous quote. That 
reads:

"""General comments and questions regarding this document should be sent 
by email to [EMAIL PROTECTED]"""

Shortly after emailing [EMAIL PROTECTED] I had an extremely polite reply 
from Fred Drake thanking me for the suggestion and agreeing to make the 
suggested change.

I don't know what stops people from jumping in with both feet, but it 
certainly isn't the unapproachability of the documentation team - all 
one of him.

> It doesn't seem like much, but as Paul Rubin mentioned, most people who 
> find bugs/unclear passages in the docs aren't scanning the docs 
> explicitly to edit them - they've uncovered the bug after working on 
> some other project, and likely only after banging their head against the 
> wall a few times trying to get it to work. If they have to go through 
> the song and dance of signing up for another website to report the 
> problem, they might just say "forget it."
> 
I can understand people's recitence, so *maybe* it would be better if 
the request for contributions clearly stated that amendments in plain 
text would be welcomed. Having done a bit of writing myself I am pretty 
sure that Fred would have to spend far less time deciding how to mark up 
some intelligent reader's plain text revisions than he would having to 
express the same thoughts coherently himself.

The developers have full-time jobs as well, so everything we can do to 
help them (I have had sourceforge commit rights in the past but I 
recently gave them up and never really regarded myself as a "developer") 
will give them more time to focus on improving the language.

> Sure, it's not hard to sign up for Sourceforge, but even a little 
> barrier can stop you from contributing if you're not enthusiastic about 
> it in the first place.
> 
I refuse to believe that it's harder to sign up for Sourceforge than it 
is to post a bitching comment on c.l.py. This is not to say that it 
couldn't be easier to contribute change suggestions to the docs, but I 
still believe that most of the bitching and moaning comes from people 
who'd rather bitch and moan than roll their sleeves up.

Otherwise it wouldn't have taken me three years to offload the PyCon 
chair (thanks, Andrew :-)

> Something a simple as allowing doc bugs to be submitted from a webform 
> w/o login would reduce the barrier to contribute. - Increasing the size 
> of the "About" text wouldn't hurt either. (To be honest, I've never 
> noticed that text before, and it never occurred to me look at the 
> "About" page for information on error reports.)
> 
So, probably the best outcome of this current dialogue would be a change 
to the bottom-of-page comment so instead of saying

"""Release 2.4, documentation updated on 29 November 2004.
See About this document... for information on suggesting changes. """

it said

"""Release 2.4, documentation updated on 29 November 2004.
See About this document... for information on suggesting changes, or 
mail your suggestions to [EMAIL PROTECTED]"""

> That said, I think the Python manuals are great. But saying that they 
> are perfect, or that the editing process couldn't be improved is just 
> deluding yourself.

Well I make a habit of deluding myself. The world is a beautiful place, 
every reader of c.l.py has my welfare at heart, and even Perl 
programmers will learn better in time; and all contributors who debate 
this topic will be happy to volunteer to help process the additional 
mails that would result from the suggested change.

I'll just point to my book and my three years as PyCon chair as an 
excuse for not getting off my butt in this particular instance :-)

with-a-sense-of-community-ly y'rs  - steve

PS Anyone who contributes will also have the delight of being able to 
point to their name at http://docs.python.org/acks.html. I was surprised 
to find I made it on that list just for a suggestion, way before I took 
on the task of documenting asyncore and asynchat.
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC http://www.holdenweb.com/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Mike Meyer]

Asbjørn Sæbø <[EMAIL PROTECTED]> writes:
> "Xah Lee" <[EMAIL PROTECTED]> writes:
>> I'm very sorry to say, that the Python doc is one of the worst possible
>> in the industry. [...]
> I suppose you are going to volounteer to fix it, then.  Right?

He once did, for one part of it. The problem he ran into was that he
was the only person who thought his version was an improvement.

He knows what constitutes good writing - or at least he knows how to
quote rules that produce good writing. Unfortunately, he doesn't seem
to be able to follow them. On top of it, his writings are typically
strewn with errors. He really needs to find somebody proof-read his
documents.

  http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Mike Meyer]

"Terry Reedy" <[EMAIL PROTECTED]> writes:
> "Rocco Moretti" <[EMAIL PROTECTED]> wrote in message 
> news:[EMAIL PROTECTED]
>> There is just one giant roadblock to that suggestion - Sourceforge
>> requires a login to post bugs/patches.
>
> After reading this and the rest of your post, and remembering others like 
> it, I decided this maybe is a real point.  Remembering that the site 
> invited emailed doc comments, I rechecked the About this Document page 
> referenced at the bottom of each doc page and found the following:
>
> "General comments and questions regarding this document should be sent by 
> email to [EMAIL PROTECTED] If you find specific errors in this document, 
> either in the content or the presentation, please report the bug at the 
> Python Bug Tracker at SourceForge."
>
> So I emailed a general suggestion (with specific wording ;-) that error 
> reports also be allowed via email -- and quoted your post to explain why.

How about extending that, and bundle a tool with python that helps a
user send a properly-formatted bug report, with prompts for all the
relevant information? This combines the nice feature of the web form -
that you get some control over the format of the report - with ease of
use.

FreeBSD, for instance, comes with the "send-pr" command, which fires
up $VISUAL on a bug report template that it's already partially filled
out from the environment. See http://tinyurl.com/7anxz > for the
man page.

That's probably not appropriate for Python. But the idea still seems
like something worthwhile to add.

   http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Sybren Stuvel]

Bryan Olson enlightened us with:
> > Why don't you help us by improving the documentation?
>
> Workin' on it.

That's all I needed to know ;-)

Sybren
-- 
The problem with the world is stupidity. Not saying there should be a
capital punishment for stupidity, but why don't we just take the
safety labels off of everything and let the problem solve itself? 
 Frank Zappa
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[A.M. Kuchling]

On Thu, 1 Sep 2005 17:09:27 +0200, 
Fredrik Lundh <[EMAIL PROTECTED]> wrote:
> the useredit approach I'm using over at the librarybook site works
> pretty well.  for example, if you go to

That looks pleasantly simple.

I don't consider the pydoc.amk.ca experiment to have been really successful.
It was a half-hour hack that's usable with some pain, but the JavaScript and
frame display needs quite a bit of polishing to be usable by a random
newbie.

There's a Firefox extension (http://www.wikalong.org/) that allows wiki
annotation, but a browser-specific annotation tool doesn't solve the general
problem.

I suspect the best solution is something Python-doc-specific that runs the
generated HTML for the docs through a preprocessor that inserts comments and
an editing form.  It would be a great topic for a user group sprint or
weekend project.

(If someone volunteers to do this: if you decide to use an RDBMS, please use
PostgreSQL, because it's already installed on one of the python.org
servers.)

--amk
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Michael Sparks]

A.M. Kuchling wrote:

> On 1 Sep 2005 05:04:33 -0700,
> Paul Boddie <[EMAIL PROTECTED]> wrote:
>> Please note that I'm not labelling you as a troll.
> 
> No, he's simply barking mad.  I was amused by a rec.arts.sf.written
> discussion [1] where Lee complains that Jonathan Swift (1667-1745)'s
> writing was unclear in style; apparently he's not aware that conventions
> and styles change over time.
> 
> --amk
> 
> [1] http://groups.google.com/group/alt.usage.english/msg/0ec9871395fc90d3

Oddly that makes me wonder if Xah Lee is a some kind of bot - given it
follows a similar fashion:
 
oh, this writing is [criticism] of [ specific]

"the "allow that" should be "allow the notion that". But the 
 whole thing is written in a confounded way. "

Specific grammar correction and note that the grammar subsystem detected too
many errors.

Better: Grammar correction suggestion. Not actually any clearer to many
people. 

more better with logicality: Similar bad parsing. A person would translate
the old style english into a more modern style if what they're doing is
criticising old english.

The whole thing just smacks to me of some text analyser. The final paragraph
contains some standard writing advice and cliches:
   * to write clearly, the first thing is to think clearly
   * get rid of big words and use  short sentences.

It'd certainly explain the online tourettes syndrome of swearing all the way
through a post - the text generator getting stuck on a particular word
sets...

Not-really-seriously :-) 
(Though usenet would be an interesting, if antisocial and annoying place to
test such a beast :-)


Michael.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Michael Sparks]

Hi Paul,


Paul Rubin wrote:
> Michael Sparks <[EMAIL PROTECTED]> writes:
[[[ some random stuff, /intended/ at supporting people who have contributed
  docs, rather than saying people who offer constructive suggestions are
  bad. Possibly badly written. ]]]
> I've submitted a number of doc bugs to sourceforge and the ones that
> are simple errors and omissions do get fixed.  

Cool. 

> However, your 
> suggestion doesn't constitute good Python advocacy, if that's what you
> were attempting.  

Nope. I rarely attempt advocacy because I'd suck at it if I tried (worse
than my docs :), and also I'm not a fan of advocacy anyway - I prefer to
make up my own mind rather than be told. 

> When I use a tool like Python, I like to think I'm 
> working on one project at a time, that project being whatever I'm
> trying to develop.  

> Telling me that whenever I use Python, I should 
> really consider myself to be working on two projects at once

I didn't mean it that way (I probably put it over the wrong way). What I did
mean is that when someone in here says "someone here should make the docs
better", is naturally including themselves in the set of people who can
write docs. If they then attack people who /can/ write docs they're
attacking themselves. 

Stating that something needs writing or updating I'd agree is good. People
whinging because no-one has written it, or constantly dissing docs without
helping improve them strikes me as unfair.

To my mind yourself, Bryan, Steve, Terry and others in the thread contribute
amazingly (and I wish I had more time to do so), by simply being nice and
helpful in *here*.

>> [ O'Reilly, and friends, books as a docs for open source ]
> 
> If those docs aren't free to redistribute, then that's not an
> open-source solution at all; if anything, it's an anti-solution, since
> it decreases the motivation to write good free docs.

OK, it's not the best solution in the world I'll agree, but my point was in
general very few people like writing docs even when paid, let alone when
not. As a result it's not that suprising IMO that if paid you end up with
more docs. 

> Even weirder is the amount of gratis (free as in beer) but unfree (as
> in freedom) docs out there for Python.  

I'm not aware of those, so I don't feel able to comment sensibly.

>> The best way to repay those who have spent the time writing what can
>> be viewed as a first draft is to provide corrections. If you
>> (generic, not just you personally) don't have the time, effort,
>> inclination or effort to summarise and feedback a documentation
>> patch *why should anyone else* ?
> 
> I usually do report doc bugs, but my frustration (and I think Bryan's)
> is that there are so many bugs in the first place.  It means that the
> authors are not applying high enough quality standards to their own
> work before releasing it.  That applies to Python's code as well as
> its docs.  It's not crap,

Or maybe they're just doing their best? It might seem silly but when I do
write docs, personally it takes me around 4-10 times longer to write the
same number of lines as documentation than as code, whilst trying to
maintain a similar quality. I think thats on a good day.

> but it's not at the level that those of us 
> from the non-Windows world like to (realistically or otherwise) expect.

FWIW, I'm not part of the windows crowd. Ceased using windows regularly
around Windows 3.1, and have periodically gone back (95, 98, ME, 2000, XP)
to see whether it's improved, and come to the conclusion for me it's a
downgrade in the way I work. It is sometimes useful for playing DVDs on
long journeys though since the power management works better IME.

[ specific example of bad or missing docs snipped ]

I agree there's always valid criticisms.

> I think there is an attitude problem in the central Python development
> community, which is to expect external volunteers to do stuff with no
> cajoling and no guidance.  That just doesn't work very well.  

I have no idea what to do about that. Giving T-Shirts to people who write a
decent tutorial that covers an entire library module? (Semi-serious if
there's a way of making that work)

> I was the first FSF staff programmer on the GNU project and we spent a LOT
> of our time coordinating volunteers and maintaining lists of tasks to
> recruit people to do, and generally trying to make stuff happen
> according to what we saw as the project's priorities, as opposed to
> simply passively waiting for code and doc contributions to come to us
> fully done.  We also saw doing gap-filling and grunt-work that didn't
> excite volunteers to be an important part of our purpose as paid
> staff: if somebody had to do it and no one volunteered, then the
> somebody was us.

This might sound really dumb, but I'd be genuinely interested to hear more
about how you organised this, how you managed to motivate people to do
these things, what "rewards" the people got for doing this. (Working on the
assumption that rewards

Re: OpenSource documentation problems

[Terry Reedy]

"Paul Rubin" <"http://phr.cx"@NOSPAM.invalid> wrote in message 
news:[EMAIL PROTECTED]
> I think there is an attitude problem in the central Python development
> community, which is to expect external volunteers to do stuff with no
> cajoling and no guidance.

You are correct.  No one has volunteered to be a volunteer volunteer 
coordinator.

 > That just doesn't work very well.

Improvements are possible, certainly.

 > I was
> the first FSF staff programmer on the GNU project and we spent a LOT
> of our time coordinating volunteers and maintaining lists of tasks to
> recruit people to do, and generally trying to make stuff happen
> according to what we saw as the project's priorities, as opposed to
> simply passively waiting for code and doc contributions to come to us
> fully done.  We also saw doing gap-filling and grunt-work that didn't
> excite volunteers to be an important part of our purpose as paid
> staff: if somebody had to do it and no one volunteered, then the
> somebody was us.

As far as I know, there currently is no paid staff for Python.  Everything 
is either volunteer or employer-donated time.  You could suggest that 
someone be paid for a few hours a week of volunteer coordination and 
explain what such work would, concretely, consist of.

>The PSF and the FSF both sometimes fund
> people to do coding projects.  Why does the PSF (apparently) not fund
> anyone to do doc projects, like the FSF does?

Last fall, PSF funded two projects out of many submissions.  Were any doc 
projects submitted.  Perhaps next round, one of us will.  One could also 
send an uninvited proposal.

This summer, Google funded about 18 Python-related Summer of Code student 
projects.  Hmm.  The title does suggest code, not docs.

Terry J. Reedy




-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Terry Reedy]

"Rocco Moretti" <[EMAIL PROTECTED]> wrote in message 
news:[EMAIL PROTECTED]
> There is just one giant roadblock to that suggestion - Sourceforge
> requires a login to post bugs/patches.

After reading this and the rest of your post, and remembering others like 
it, I decided this maybe is a real point.  Remembering that the site 
invited emailed doc comments, I rechecked the About this Document page 
referenced at the bottom of each doc page and found the following:

"General comments and questions regarding this document should be sent by 
email to [EMAIL PROTECTED] If you find specific errors in this document, 
either in the content or the presentation, please report the bug at the 
Python Bug Tracker at SourceForge."

So I emailed a general suggestion (with specific wording ;-) that error 
reports also be allowed via email -- and quoted your post to explain why.

Terry J. Reedy



-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Paul Rubin]

"Fredrik Lundh" <[EMAIL PROTECTED]> writes:
> another problem is that to be able to do really good work on the
> documentation, you need to know things well enough to "have the
> big picture".  and once you have that, you'll find that the docs aren't
> really as bad as you once thought they were.

One thing that might help is a comments/questions area on each online
doc page, like PHP has.  That would let users easily point out the
areas where the docs need improvement, and collect wisdom about the
library functions attached to the docs for those functions instead of
getting it lost in clpy archives.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Alan Balmer]

On 1 Sep 2005 03:51:55 -0700, "Xah Lee" <[EMAIL PROTECTED]> wrote:

>On Python's Documentation

Thinking about it, I can't imagine why I've waited so long to filter
this idiot.
-- 
Al Balmer
Balmer Consulting
[EMAIL PROTECTED]
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Randy Bush]

> I'm very sorry to say, that the Python doc is one of the worst possible
> in the industry.

you are entitled to a full refund

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Paul Boddie]

A.M. Kuchling wrote:
> I was amused by a rec.arts.sf.written discussion [1] where Lee complains that
> Jonathan Swift (1667-1745)'s writing was unclear in style; apparently he's 
> not aware
> that conventions and styles change over time.

Still, ill-founded assumptions about language could be much worse:

http://www.wisdomquotes.com/000536.html

Paul

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Rich Teer]

On Thu, 1 Sep 2005, Asbjørn Sæbø wrote:

> I suppose you are going to volounteer to fix it, then.  Right?

I wish he'd just volunteer to shut up--permanently.

-- 
Rich Teer, SCNA, SCSA, OpenSolaris CAB member

President,
Rite Online Inc.

Voice: +1 (250) 979-1638
URL: http://www.rite-group.com/rich
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Fredrik Lundh]

Rocco Moretti wrote:

> Something a simple as allowing doc bugs to be submitted from a webform
> w/o login would reduce the barrier to contribute. - Increasing the size
> of the "About" text wouldn't hurt either. (To be honest, I've never
> noticed that text before, and it never occurred to me look at the
> "About" page for information on error reports.)

the useredit approach I'm using over at the librarybook site works
pretty well.  for example, if you go to

http://effbot.org/librarybook/mailbox.htm

and click "suggest changes" at the bottom, you can edit the page
source, preview the changes, and generate a patch when you're
done, all without signing up or logging in.

(unfortunately, Python's documentation is written in LaTeX, using
a rather advanced tool chain to get from sources to HTML, so the
librarybook approach won't really work "out of the box")

 



-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Rocco Moretti]

Steve Holden wrote:

> Every page of the docs links to "About this document", which contains 
> the following: """If you are able to provide suggested text, either to 
> replace existing incorrect or unclear material, or additional text to 
> supplement what's already available, we'd appreciate the contribution. 
> There's no need to worry about text markup; our documentation team will 
> gladly take care of that."""

There is just one giant roadblock to that suggestion - Sourceforge 
requires a login to post bugs/patches.

It doesn't seem like much, but as Paul Rubin mentioned, most people who 
find bugs/unclear passages in the docs aren't scanning the docs 
explicitly to edit them - they've uncovered the bug after working on 
some other project, and likely only after banging their head against the 
wall a few times trying to get it to work. If they have to go through 
the song and dance of signing up for another website to report the 
problem, they might just say "forget it."

Sure, it's not hard to sign up for Sourceforge, but even a little 
barrier can stop you from contributing if you're not enthusiastic about 
it in the first place.

Something a simple as allowing doc bugs to be submitted from a webform 
w/o login would reduce the barrier to contribute. - Increasing the size 
of the "About" text wouldn't hurt either. (To be honest, I've never 
noticed that text before, and it never occurred to me look at the 
"About" page for information on error reports.)

That said, I think the Python manuals are great. But saying that they 
are perfect, or that the editing process couldn't be improved is just 
deluding yourself.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[A.M. Kuchling]

On Wed, 31 Aug 2005 19:57:00 GMT, 
Bryan Olson <[EMAIL PROTECTED]> wrote:
> Since "help *is* pydoc.help, or at least...", the call could
> show the same thing as help(pydoc.help), or at least inform the
> user that more of the story is available from help(pydoc.help).

But, given that the help message encourages the user to type help(), I don't
think this odd corner case matters very much.

> How about to fix the error?

That's now done; I've struck the sentence from the CVS version, and pointed
readers toward the zlib manual.

--amk
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[A.M. Kuchling]

On 1 Sep 2005 05:04:33 -0700, 
Paul Boddie <[EMAIL PROTECTED]> wrote:
> Please note that I'm not labelling you as a troll.

No, he's simply barking mad.  I was amused by a rec.arts.sf.written 
discussion [1] where Lee complains that Jonathan Swift (1667-1745)'s writing
was unclear in style; apparently he's not aware that conventions and styles
change over time.

--amk

[1] http://groups.google.com/group/alt.usage.english/msg/0ec9871395fc90d3
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Asbjørn Sæbø]

"Xah Lee" <[EMAIL PROTECTED]> writes:


> I'm very sorry to say, that the Python doc is one of the worst possible
> in the industry. [...]

I suppose you are going to volounteer to fix it, then.  Right?

Asbjørn
-- 
Asbjørn Sæbø, post.doc. 
Centre for Quantifiable Quality of Service in Communication Systems
Norwegian University of Science and Technology
http://www.q2s.ntnu.no/ >
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Paul Boddie]

Xah Lee wrote:
> The "Language Reference" section (subtitled "for language
> lawyers") needs to be replaced by human-readible descriptions of
> Python's functions. For exapmle, in the style of official Java doc
> (http://java.sun.com/j2se/1.4.2/docs/api/index.html).

Nope. The Java documentation you're referring to corresponds to the
"Library Reference" in Python, which is a collection of human-readable
descriptions of Python's functions (whether you like them or not).
Meanwhile, the corresponding Java documentation for Python's "Language
Reference" is this document collection:

http://java.sun.com/docs/books/jls/second_edition/html/jTOC.doc.html

You'll notice that it resembles the Python documentation rather
strongly. I'm afraid that the "Computer Science Pretension" is
necessary with that kind of documentation so that "language lawyers" -
ie. people implementing compilers, runtimes, tools - don't create
something that doesn't work with genuine specimens of the language.

Now, I don't doubt that Python's documentation could be improved, and
I'm willing to improve it (and have improved it in the past). I even
ticked the box on some feedback form at EuroPython to say that I'm
willing to write Python docs. In fact, I may start looking at the
documentation tasks on the Wiki and seeing what I can contribute,
possibly from stuff I've already written but which doesn't trivially
slot into the documentation as it is today. And I don't disagree with
you that the PythonInfo Wiki is a structural mess (I can never manage
to navigate from the front page to the WebProgramming page, although I
obviously know the name of the page and don't need to, but this isn't
going to help someone who doesn't know that it's there), nor do I
disagree with you that TeX isn't exactly the most accessible
technology.

However, I would recommend that in order to be taken more seriously you
tone down the rhetoric, review the available documentation (including
stuff like "Dive Into Python" http://www.diveintopython.org/) and note
the actual purpose of that documentation (eg. language vs. library
reference) before suggesting the replacement of one text with another
that already exists.

> (in this respect, similar to how wikipedia's texts drift into a form of 
> academic
> esoterica whose educational value and readibility are greatly reduced
> to the general public.)

And here's an example of that rhetoric I referred to. Personally, I
find Wikipedia very readable even for my increasingly shortening
attention span, and some academics would presumably argue that
Wikipedia has already crossed some kind of line of compromise between
accessibility and thoroughness. If you want things like the 1707 Act of
Union (http://en.wikipedia.org/wiki/Act_of_Union_1707) explained to you
without "esoterica", perhaps that says more about you than it does
about Wikipedia.

Please note that I'm not labelling you as a troll. As far as I can
tell, many of your ideas are fairly sound; it's just that it's hard
work to see past the rhetoric and posturing, which is a shame because
you quite possibly have a lot to contribute.

Paul

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Fredrik Lundh]

Steve Holden wrote:

> I agree that maintaining documentation is a generic problem of the open
> source world, but it's a sad fact of life that generally people are
> better-motivated to complain about documentation (and almost everything
> else) than to help improve it.

another problem is that to be able to do really good work on the
documentation, you need to know things well enough to "have the
big picture".  and once you have that, you'll find that the docs aren't
really as bad as you once thought they were.

 



-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Xah Lee]

On Python's Documentation

Xah Lee, 20050831

I'm very sorry to say, that the Python doc is one of the worst possible
in the industry. I'm very sick of Perl and its intentional obfuscation
and juvenile drivel style of its docs. I always wanted to learn Python
as a replacement of Perl, and this year i did. I thought Python is much
better. But now i know, that although the language is better, but its
documentation is effectively worse than Perl's.

• Official Perl doc: http://www.perl.com/pub/v/documentation
• Official Python doc: http://python.org/doc/2.4.1/


The Perl docs, although lousy in the outset because its people immerse
in drivel. It is part of their unix culture. Nevertheless, one thing
Perl doc is not, is that it in particular do not presume a superficial
Computer Science stance. In fact, its culture sneer computer science
establishment. (which caused major harm in the industry) There are
quite a lot things wrong with Perl docs. But at least it is not shy to
use examples, lots of them.

Now, i have thought that Python doc is entirely different. The Python
community in many ways are antithesis of Perl community. Python doesn't
start with a hacking mentality, and i presume its people care a lot
more about correctness and quality. Unfortunately, as i now know, its
doc is even worse than Perl's. Several problems lie at the core:

  its technical writing is extremely poor. (likewise Perl)

  its technical content clearly shows that the writers can't or
didn't think clearly. (one confused ball; likewise Perl)

  its organization exhibits the worst abstruse insensibilities of
tech geekers. (likewise Perl, exemplified by the infamous unix man
pages, but at least Perl/unix has spunk)

  its organization and content presentation has a computer science
pretension.

The Computer Science Pretension aspect is the most egregious that does
the most damage to the Python doc. The text became incomprehensible
abstraction sans any example, and impossible to locate desired
functionalities. Much like unix man pages, it requires the reader to
have familiarity with the entire doc to be able to use it fruitfully.

As i have expressed before (see
http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html ), the
python doc has huge number of problems. To remedy them, it needs major
overhaul if not complete rewrite.

Just about the only worthwhile part of the official doc set is the
Tutorial section.

The “Language Reference” section (subtitled “for language
lawyers”) needs to be replaced by human-readible descriptions of
Python's functions. For exapmle, in the style of official Java doc
(http://java.sun.com/j2se/1.4.2/docs/api/index.html). The Library
Reference section and The Global Module Index are all in a very not
useful state. These 3 section are all a incomprehensible blurr.

i haven't read much of the other sections:

• Macintosh Library Modules
  (for language lawyers)
• Extending and Embedding
  (tutorial for C/C++ programmers)
• Python/C API
  (reference for C/C++ programmers)
• Documenting Python
  (information for documentation authors)
• Installing Python Modules
  (information for installers & sys-admins)
• Distributing Python Modules


but all these should probably not be bundled with the official doc set.

I would like to see the Python doc gets a complete rewrite.

First of all, the doc system LaTeX needs to go. (TeX itself is a
OpenSource crime, and its use as Python's doc system is a illustration
of damage. See this unedited rant
http://xahlee.org/Periodic_dosage_dir/t2/TeX_pestilence.html )

Then, the doc needs to be written with a few principles.

  to communicate to programers how to use it. (as opposed to being a
semi description of implementation and compiler process, or inline with
some computer sciency model or software engineering metholodogy fad)

  write with the goal of effective communication. In writing, avoid
highbrow words, long sentences, and do focus on concision and
precision. In content, avoid philosophical outlook, jargon population,
author masturbation, arcane technicalities, gratuitous cautions, geek
tips, juvenile coolness ... etc.)

  document with consideration of programer's tasks to be performed.

  document orient with the language's exhibited functionalities,
concrete behaviors. (as opposed to in some milieu of computer sciency
model.)

  give ample examples.

(for detail, study several of my Python criticisms from the link
mentioned above)

I have not been in the Python community long and have not delved into
it. Is there other documentation that can be a basis of a new Python
doc? The one i know is the Quick Reference by Richard Gruet. (
http://rgruet.free.fr/PQR24/PQR2.4.html ) As a quick reference, it
provides a concrete documentation of Python functionalities, and is a
excellent basis for new documentation. However, being a Quick Reference
it is very terse, consequently needs a lot work if it is to be a full
documentation.

Of course, the other major hurdle in prog

Re: OpenSource documentation problems

[Xah Lee]

By the way, i have sent my criticisms to the proper python doc
maintainer or mailing list several months ago.

-

i'm very sorry to say, that the Python doc is one of the worst possible
in the industry. I'm very sick of Perl and its intentional obfuscation
and juvenile drivel style of its docs. I always wanted to learn Python
as a replacement of Perl, and this year i did. I thought Python is much
better. But now i know, that although the language is better, but its
documentation is effectively worse than Perl's.

The Perl docs, although lousy in the outset because its people immerse
in drivel. It is part of their unix culture. Nevertheless, one thing
Perl doc is not, is that it in particular do not presume a superficial
Computer Science stance. In fact, its culture sneer computer science
establishment. (which i caused major harm in the industry) There are
quite a lot things wrong with Perl docs. But at least it is not shy to
use examples, lots of them.

Now, i have thought that Python doc is entirely different. The Python
community in many ways are antithesis of Perl community. Python doesn't
start with a hacking mentality, and i presume it to have a community
who care about correctness and quality. Unfortunately, as i now know,
its doc is the worst and almost useless piece of shit. Several problems
lies at the core:

* its technical writing is extremely poor.

* its technical content clearly shows that the writers can't or didn't
think clearly. (one confused ball)

* its organization exhibits the worst abstruse insensibilities of tech
geekers.



as i have expressed before (see
http://xahlee.org/Periodic_dosage_dir/t2/xlali_skami_cukta.html
), the python doc has huge number of problems. To remedy them, it needs
major overhaul if not complete rewrite.

Just about the only worthwhile part of the official doc set is the
Tutorial section. The “Language Reference” section, Library
Reference, and The Global Module Index are totally crap and need to be
deleted entirely. (i haven't read much of the other sections, but i
don't assume they are much better)

-

I would like to see the Python doc gets a complete rewrite.

First of all, the doc system LaTex needs to go. (TeX itself is a
OpenSource crime, see this unedited rant
http://xahlee.org/Periodic_dosage_dir/t2/TeX_pestilence.html
)

Then, the doc needs to be written with a few principles.

* to communicate to programers how to use it. (as opposed to being a
compiling specification or inline with some computer sciency model)

* write with the goal of effective communication. In the writing, avoid
big Engish words, long sentences, and focus on precision. In content,
avoid philosophical outlook, jargon population, author masturbation,
arcane technicalities, gratuitous cautions, geek tips, juvenile
coolness ... etc.)

* document with consideration of tasks to be performed.

* document orient with the language's exhibited functionalities,
concrete behaviors. (as opposed to in some milieu of software
engineering methodology)

* give ample examples.

(for detail, study several of my Python criticisms from the link
mentioned above)

--

I have not been in the Python community long and have not delved into
it. Is there other documentation that can be a basis of a new python
doc? The one i know is the Quick Reference by Richard Gruet. However,
it is just a Quick Reference but can be a basis if we lack anything
else.

Also, i have happened to read the O'Reilly Python book years ago. That
book is crap. I have also read parts of the Python Cookbook. Probably
half of this book is also crap.

Of course, the other major hurdle in progress (for a new doc) is a
political one. It is, alas, always the biggest problem.
---

the python doc wiki given at
http://pydoc.amk.ca/frame.html
is a great idea. For this to work, there are two things needs to be
done, both are equally important:

1. for the official python site Python.org to point to the wiki as THE
official python doc.

2. given a authoritarian guide in the wiki on how to write the doc.
(the guide based on the principles i gave above. Of course, it needs to
be clarified and elaborated with many cases in point.)

Without (1), the wiki will never be prominent. Without (2), it will
remain a geek drivel. (in this respect, similar to how wikipedia's
texts drift into a form of academic esoterica whose educational value
are greatly reduced to the general public.)


this post is archived at
http://xahlee.org/UnixResource_dir/writ/python_doc.html

 Xah
 [EMAIL PROTECTED]
∑ http://xahlee.org/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Bryan Olson]

Fredrik Lundh wrote:
 > Bryan Olson wrote:
 >> import pydoc
 >> help is pydoc.help
 >> >
 >> > False
 >>
 >>Say Fredrik, if you're going to proclaim "False"
 >
 > oh, I didn't proclaim anything.  Python 2.4 did.

False. ;)  That was all you.

 > let's see what
 > Python 2.2 has to say about this:
 >
 > $ python2.2
 > Python 2.2.1 (#2, Jul 17 2002, 13:11:01)
 > [GCC 2.96 2731 (Red Hat Linux 7.1 2.96-98)] on linux2
 > Type "help", "copyright", "credits" or "license" for more information.
 >
 import pydoc
 help is pydoc.help
 >
 > 0

You might look at what Mr. Kutching actually wrote:

 help *is* pydoc.help, or at least a trivial wrapper around it

or how I quoted that:

 Since "help *is* pydoc.help, or at least...", the call could

Missed that 'or' did you?

Since 'or' is a Python keyword, let's follow your procedure, and
see if Python (the current version this time) can clue us in as
to what it means.

 >>> help('or')

 Sorry, topic and keyword documentation is not available
 because the Python HTML documentation files could not be
 found.  If you have installed them, please set the
 environment variable PYTHONDOCS to indicate their location.

Darn. I just did the standard Windows install, so I kinda hoped
it would set things up the way it needs them. Oh, well I'll push
on and set the environment variable.

Hmmm... no joy. Same message. What's going on? Well, let's look
up the pydoc module.

 http://docs.python.org/lib/module-pydoc.html

 Module docs for core modules are assumed to reside in
 http://www.python.org/doc/current/lib/. This can be
 overridden by setting the PYTHONDOCS environment variable to
 a different URL or to a local directory containing the
 Library Reference Manual pages.

Odd, it looks like setting the PYTHONDOCS variable isn't even
supposed to be required.

O.K. Next the source: ; Ah,
problem in pydoc.Helper.__init__:

 for dir in [os.environ.get('PYTHONDOCS'),
 homedir and os.path.join(homedir, 'doc'),
 os.path.join(execdir, 'doc'),
 '/usr/doc/python-docs-' + split(sys.version)[0],
 '/usr/doc/python-' + split(sys.version)[0],
 '/usr/doc/python-docs-' + sys.version[:3],
 '/usr/doc/python-' + sys.version[:3],
 os.path.join(sys.prefix, 
'Resources/English.lproj/Documentation')]:
 if dir and os.path.isdir(os.path.join(dir, 'lib')):
 self.docdir = dir

Obviously that's not going to find the URL.

Still, it looks like it's trying to find the doc/ directory in
the PYTHONDOCS environment variable. I'm not sure why it's
looking for 'lib' as a subdirectory when the pydoc documentation
said to set the environment variable to the directory with the
library doc. (Also, I can't quite fathom why the loop goes on
searching after it finds what it seem to be looking for.)

Next thing to check is whether the doc/ directory has a 'lib/'
subdirectory as the code seems to expect.  Aha: no such
subdirectory. On the Windows install, doc/ contains one file:
'Python24.chm' and no subdirectories. Probably one of those out-
of-sync change issues.

I submitted the bug report at Sourceforge.


 > I do, however, find it a bit funny when someone reads
 >
 > Type "help", "copyright", "credits" or "license" for more 
information.
 >
 > as
 >
 > Type "help(help)" /.../
 >
 > and then starts ranting about how "help(help)" isn't quite as helpful
 > as "help" (or "help()", for that matter -- which is what a plain "help"
 > tells you to use).

Is it your baby that's ugly this time? Sorry, but snipping and
pretending people said what they didn't is a low-class move.

 > it's a little like the people who type "google" into the google search
 > field, and then complain that the "I feel lucky" button doesn't seem
 > to work.

Googling Google works fine. Python's doc, not so much.


-- 
--Bryan
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Paul Rubin]

Michael Sparks <[EMAIL PROTECTED]> writes:
> > A plausible theory. I have some possibly-illustrative examples
> > of what I ran into within the last few weeks.
> 
>  Did you take what you learnt, and use that to create better
> documentation to be posted on python's SF project as a patch?
>  

I've submitted a number of doc bugs to sourceforge and the ones that
are simple errors and omissions do get fixed.  However, your
suggestion doesn't constitute good Python advocacy, if that's what you
were attempting.  When I use a tool like Python, I like to think I'm
working on one project at a time, that project being whatever I'm
trying to develop.  Telling me that whenever I use Python, I should
really consider myself to be working on two projects at once (doing my
own project, plus helping develop Python or its docs) makes it sound
like you're recommending a tool that has no intention of ever really
leaving beta test.  

Python's docs are nowhere near the worst I've seen, but I have to say
that various other free software projects manage to hold to higher
standards for both code and documentation than Python seems to deem
worth bothering with.  I have a theory about why this might be, which
starts with W and comes from Redmond.  But I'll skip that.

> Ironically though I do think the problem of documentation has been
> half solved in the open source world, and it really boils down (IMO)
> to companies like O'Reilly who appear to try and target popular
> not-best-documented open source projects and provide the
> motivation that results in good documentation.

If those docs aren't free to redistribute, then that's not an
open-source solution at all; if anything, it's an anti-solution, since
it decreases the motivation to write good free docs.

Even weirder is the amount of gratis (free as in beer) but unfree (as
in freedom) docs out there for Python.  I'm thinking of docs like like
John Shipman's Tkinter reference manual from nmt.edu, which while not
perfect is extremely useful.  There's no money being collected for it,
and thus no profit motive for not explicitly licensing it under terms
that allow including it in Python and other free software distros, and
yet this isn't being done.  Somewhat more understandable, but also
counterproductive to Python as a FOSS project, is semi-gratis stuff
like the ASPN docs.

> The best way to repay those who have spent the time writing what can
> be viewed as a first draft is to provide corrections. If you
> (generic, not just you personally) don't have the time, effort,
> inclination or effort to summarise and feedback a documentation
> patch *why should anyone else* ?

I usually do report doc bugs, but my frustration (and I think Bryan's)
is that there are so many bugs in the first place.  It means that the
authors are not applying high enough quality standards to their own
work before releasing it.  That applies to Python's code as well as
its docs.  It's not crap, but it's not at the level that those of us
from the non-Windows world like to (realistically or otherwise) expect.

> When people complain /in here/ about the documentation not being
> perfect for python I personally find it sad and ironic. It's sad
> because it says to the person who spent their time (when they could
> be doing something else) that they wasted it, the docs are worthless
> etc - when they clearly *haven't* wasted their time and the docs are
> worthwhile.

I don't understand what you mean by that.  For example, there are
practically no useful Tkinter docs in the Python distro.  That is a
legitimate gripe against Python.  There's a workaround in the form of
some docs available from external sources (above).

I think there is an attitude problem in the central Python development
community, which is to expect external volunteers to do stuff with no
cajoling and no guidance.  That just doesn't work very well.  I was
the first FSF staff programmer on the GNU project and we spent a LOT
of our time coordinating volunteers and maintaining lists of tasks to
recruit people to do, and generally trying to make stuff happen
according to what we saw as the project's priorities, as opposed to
simply passively waiting for code and doc contributions to come to us
fully done.  We also saw doing gap-filling and grunt-work that didn't
excite volunteers to be an important part of our purpose as paid
staff: if somebody had to do it and no one volunteered, then the
somebody was us.

The FSF's emphasis has changed somewhat since then, but my (admittedly
biased) opinion remains that the quality of the work we did in those
days, both in code and docs, was better than what I see coming out of
Python.org today.  We didn't have more talent or resources or anything
like that.  We just had a different attitude, of trying to do stuff
right whenever we could, and to provide a driving force rather than
waiting for stuff to happen without our initiative.  (It helped that
RMS was very intolerant of sloppiness, and he raised everyone

Re: OpenSource documentation problems

[Bryan Olson]

Michael Sparks wrote:
> Bryan Olson wrote:
>>A plausible theory. I have some possibly-illustrative examples
>>of what I ran into within the last few weeks.
> 
> 
>  Did you take what you learnt, and use that to create better
> documentation to be posted on python's SF project as a patch?
>  
> 
> (Not aimed at you, just a preface, and you also provided the right "starter
> point" to my main comment :)

In the past few weeks I've submitted my first official bug-report
for Python, and my first PEP. I didn't have time to address every
problem.


-- 
--Bryan
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Terry Reedy]

"Robert Kern" <[EMAIL PROTECTED]> wrote in message 
news:[EMAIL PROTECTED]
> Or perhaps more to the point, that http://pydoc.amk.ca/frame.html should
> be better-publicized.

This seems to be an experiment that has not been updated since 2.3.4.

tjr



-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Terry Reedy]

> Bryan Olson wrote:
>> Whatever else one says about open-source documentation, keeping
>> it current is a major unsolved problem.

Python does pretty well.  Doc updates, when needed, are an expected part of 
patches.  Every couple of months or so, F. Drake releases a new 
'development version' of the docs which I presume is synched with the 
current development version of the code.  So when x.y.z or x.y.alpha1 is 
released, there should not be a hugh scramble to cobble together a 
corresponding doc set.

The process is not perfect: people still find mismatches.  But complaints 
about 'f**king docs' are truly obscene (IMO).

Terry J. Reedy



-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Robert Kern]

Steve Holden wrote:
> Terry Hancock wrote:

>>Perhaps this just reduces to "there ought to be a wiki"?
> 
> Well, perhaps the Wiki at http://wiki.python.org/moin/ should also be 
> better-publicized, then?

Or perhaps more to the point, that http://pydoc.amk.ca/frame.html should
be better-publicized.

-- 
Robert Kern
[EMAIL PROTECTED]

"In the fields of hell where the grass grows high
 Are the graves of dreams allowed to die."
  -- Richard Harter

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Steve Holden]

Terry Hancock wrote:
> On Wednesday 31 August 2005 07:05 pm, Michael Sparks wrote:
> 
>>When people complain /in here/ about the documentation not being perfect for
>>python I personally find it sad and ironic. It's sad because it says to the
>>person who spent their time (when they could be doing something else) that
>>they wasted it, the docs are worthless etc - when they clearly *haven't*
>>wasted their time and the docs are worthwhile. It's ironic though because
>>they're criticising themselves. After all they understand how the docs can
>>be better and the docs are shared. Unless they contribute back they're
>>actually attacking themselves as much as the person who "wastes" their time
>>writing "worthless" docs.
> 
> 
> There is one criticism however, which I think is valid, which could
> be fixed, and which would probably leverage community effort better:
> it could probably be a lot easier to contribute to the documentation.
> 
> I haven't attempted it myself, but my understanding is that there
> is something of a learning curve to producing documentation using
> the docutils.  This has the effect of excluding anyone from
> contributing who is not willing to overcome that learning curve.
> 
> In order to make that tradeoff worthwhile, the potential contributor
> must have a pretty serious objection to the documentation and/or a
> fairly large amount of changes that they want to make. Furthermore,
> they have to have convinced themselves that it's worthwhile, which
> means they have to be acknowledging that they will contribute
> significantly in the future.  All of which adds up to not many people
> taking the trouble to improve the documentation.
> 
Probably it should simply be made better-known that patches to the 
documentation don't have to be in the correct source form (docutils 
aren't used, by the way, it's a LaTeX-based system). I've seen 
statements by both Fred Drake and Skip Montanaro that they would be 
happy to accept text and put it in the right format.

Every page of the docs links to "About this document", which contains 
the following: """If you are able to provide suggested text, either to 
replace existing incorrect or unclear material, or additional text to 
supplement what's already available, we'd appreciate the contribution. 
There's no need to worry about text markup; our documentation team will 
gladly take care of that."""

So the learning curve needn't bother the casual contributor, but I 
suspect that few such potential contributors know about this.

> For those who do, of course, the current implementation is fine.
> But if the argument is that more community involvement is needed,
> then maybe the system needs to be more efficient at capturing
> that effort, by lowering the barriers to contribution.
> 
> Perhaps this just reduces to "there ought to be a wiki"?
> 
Well, perhaps the Wiki at http://wiki.python.org/moin/ should also be 
better-publicized, then?

I agree that maintaining documentation is a generic problem of the open 
source world, but it's a sad fact of life that generally people are 
better-motivated to complain about documentation (and almost everything 
else) than to help improve it.

Given that often people appear on this list for the first time without 
having used Google or the docs to try and find an answer to their 
questions, these complaints are likely to continue indefinitely ...

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC http://www.holdenweb.com/

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Terry Hancock]

On Wednesday 31 August 2005 07:05 pm, Michael Sparks wrote:
> When people complain /in here/ about the documentation not being perfect for
> python I personally find it sad and ironic. It's sad because it says to the
> person who spent their time (when they could be doing something else) that
> they wasted it, the docs are worthless etc - when they clearly *haven't*
> wasted their time and the docs are worthwhile. It's ironic though because
> they're criticising themselves. After all they understand how the docs can
> be better and the docs are shared. Unless they contribute back they're
> actually attacking themselves as much as the person who "wastes" their time
> writing "worthless" docs.

There is one criticism however, which I think is valid, which could
be fixed, and which would probably leverage community effort better:
it could probably be a lot easier to contribute to the documentation.

I haven't attempted it myself, but my understanding is that there
is something of a learning curve to producing documentation using
the docutils.  This has the effect of excluding anyone from
contributing who is not willing to overcome that learning curve.

In order to make that tradeoff worthwhile, the potential contributor
must have a pretty serious objection to the documentation and/or a
fairly large amount of changes that they want to make. Furthermore,
they have to have convinced themselves that it's worthwhile, which
means they have to be acknowledging that they will contribute
significantly in the future.  All of which adds up to not many people
taking the trouble to improve the documentation.

For those who do, of course, the current implementation is fine.
But if the argument is that more community involvement is needed,
then maybe the system needs to be more efficient at capturing
that effort, by lowering the barriers to contribution.

Perhaps this just reduces to "there ought to be a wiki"?

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Michael Sparks]

Bryan Olson wrote:

> A plausible theory. I have some possibly-illustrative examples
> of what I ran into within the last few weeks.

 Did you take what you learnt, and use that to create better
documentation to be posted on python's SF project as a patch?
 

(Not aimed at you, just a preface, and you also provided the right "starter
point" to my main comment :)

> Whatever else one says about open-source documentation, keeping
> it current is a major unsolved problem.

I agree. However, the reason for this is very simple: most people who write
open source software (especially so AFAICT with python) do so on their own
time. In my experience its very difficult to get professional programmers
when they're being paid to write good documentation, and this is /despite/
the possible alternatives.

Add in the fact that part of the problem is that ability to write good code
doesn't always equate to the ability to write good documentation. Also add
in that the desire to write code isn't always accompanied by the desire to
write documentation.

Taking all that into account if it's difficult to get people who are paid
to do these things to write decent documentation (which is why people
hire tech writers), I find it suprising that people expect open source
developers to spend their own time producing high quality documentation,
which may in fact be a skill some of them lack.

Ironically though I do think the problem of documentation has been
half solved in the open source world, and it really boils down (IMO)
to companies like O'Reilly who appear to try and target popular
not-best-documented open source projects and provide the
motivation that results in good documentation.

As things go, python is pretty well documented IMO. Sure there's weak
areas, but considering this is all stuff people have done largely on their
own time, and anyone who's written docs knows it's not fun. The best way to
repay those who have spent the time writing what can be viewed as a first
draft is to provide corrections. If you (generic, not just you personally)
don't have the time, effort, inclination or effort to summarise and
feedback a documentation patch *why should anyone else* ?

When people complain /in here/ about the documentation not being perfect for
python I personally find it sad and ironic. It's sad because it says to the
person who spent their time (when they could be doing something else) that
they wasted it, the docs are worthless etc - when they clearly *haven't*
wasted their time and the docs are worthwhile. It's ironic though because
they're criticising themselves. After all they understand how the docs can
be better and the docs are shared. Unless they contribute back they're
actually attacking themselves as much as the person who "wastes" their time
writing "worthless" docs.

(Again, not specifically aimed at you, but unless you've actually
contributed back the results of your findings, you have to realise that any
reasons or excuses that apply to you may also apply to anyone/everyone in
the group and it's therefore suprising we have any docs ! :-)

Best Regards,


Michael.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Fredrik Lundh]

Bryan Olson wrote:

>  import pydoc
>  help is pydoc.help
>  >
>  > False
>
> Say Fredrik, if you're going to proclaim "False"

oh, I didn't proclaim anything.  Python 2.4 did.  let's see what
Python 2.2 has to say about this:

$ python2.2
Python 2.2.1 (#2, Jul 17 2002, 13:11:01)
[GCC 2.96 2731 (Red Hat Linux 7.1 2.96-98)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import pydoc
>>> help is pydoc.help
0

I do, however, find it a bit funny when someone reads

Type "help", "copyright", "credits" or "license" for more information.

as

Type "help(help)" /.../

and then starts ranting about how "help(help)" isn't quite as helpful
as "help" (or "help()", for that matter -- which is what a plain "help"
tells you to use).

it's a little like the people who type "google" into the google search
field, and then complain that the "I feel lucky" button doesn't seem
to work.





-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Bryan Olson]

Sybren Stuvel wrote:
 > I don't have any problems with the documentation. It just works for
 > me. If you find any errors or omissions, fix them and send the
 > document maintainer an email. Why don't you help us by improving the
 > documentation?

Workin' on it.


-- 
--Bryan
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Bryan Olson]

Fredrik Lundh wrote:
 > Bryan Olson wrote:
 >>[...]
 >> > What additions to that string would you suggest?
 >>
 >>Since "help *is* pydoc.help, or at least...", the call could
 >>show the same thing as help(pydoc.help)
 >
 >
 import pydoc
 help is pydoc.help
 >
 > False

Say Fredrik, if you're going to proclaim "False", I'd ask that
you include the " wrote:" that notes the writer who
made the false claim. Your current style almost looks as though
you're saying I wrote something that isn't true.


-- 
--Bryan
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Fredrik Lundh]

Bryan Olson wrote:

> [...]
>  > What additions to that string would you suggest?
>
> Since "help *is* pydoc.help, or at least...", the call could
> show the same thing as help(pydoc.help)

>>> import pydoc
>>> help is pydoc.help
False

> or at least inform the user that more of the story is available
> from help(pydoc.help).

>>> help
Type help() for interactive help, or help(object) for help about object.


>>> help()

Welcome to Python 2.4!  This is the online help utility.

If this is your first time using Python, you should definitely check out
the tutorial on the Internet at http://www.python.org/doc/tut/.

/.../

(if you read and followed the instructions, you wouldn't have to post
quite as many "THIS IS BROKEN! THE SKY IS FALLING!" posts.)





-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Terry Hancock]

On Wednesday 31 August 2005 07:14 am, Bryan Olson wrote:
> Terry Hancock wrote:
>  > Bryan Olson wrote:
> Then how does one distinguish stable, supported services, from
> incidental behavior that can change without notice?

Surprisingly often, "common sense" seems to be a workable answer
here. I'm not being sarcastic, but I do find that the changes in
Python over different versions have generally not caused a lot
of surprise for me.

I admit that's a weak answer.
 
>  > 4) But if you want a more theoretical and explained version of the
>  > language, there's always the "Language Reference".
> 
> Which is what steered me wrong on the behavior of slice objects:

Huh. Well, I always consider slices a bit tricky, so I always test those
things out in the interpreter before using them in a real program. I
guess that's why they don't bother me.

> Whatever else one says about open-source documentation, keeping
> it current is a major unsolved problem.

Yes. But I think the real problem is that the nature of open-source
documentation ensures that the old, out-of-date version will always
be competing with the newer version.  Dates on documentation are not
only not always kept up, but even when they are, they are often
deceptive (e.g. they don't actually reflect the last update or
the last update ignored significant outdated material).

Then again, I saw a textbook with a very similar problem not that
long ago. There was a reference to a certain thing being common
"20 years ago", but I was pretty sure it's more like 40.  I suspect
that it was copied from a 20-year-old edition of the same book
without being updated.

>  > I have NEVER seen a closed source application or programming
>  > language that came with that much documentation and support.
> 
> I'm no fan of Microsoft, but in general, the Win32 API is far
> better documented than is Python. (Just don't use the searching
> facilities on the MSDev CD's to find the doc; Google it up.)

Okay, I was being a little bit tricky here, too.  I said I'd
*never seen* better documentation on a closed source application.
It's unclear to me whether that means it doesn't exist, or I just
can't get hold of it, because it's closed source code.

> [...]
>  > I also have to say, that as a module writer, Python's support
>  > for self-documenting code or "literate programming" is excellent.
>  > I'm really coming to appreciate the value of this.
> 
> Unfortunately, it's also full of traps.

Sorry?  I missed that part.  What "traps" are you referring to?

I can see for example that there's more than one mark-up language
for doc strings and I wasn't too happy with the state of happydoc,
which has apparently never been fully updated to version 3.  So
I converted to epydoc. This did not take a massive amount of time,
though.

If there are "traps", I think I would like to hear more about it.

Cheers,
Terry

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Terry Hancock]

On Tuesday 30 August 2005 05:15 pm, Benji York wrote:
> Terry Hancock wrote:
> > OTOH, there are lots of poorly-documented third-party Python
> > modules (as in any language).  Zope is a particularly nasty
> > example -- though I think I understand some of the reasons 
> > behind that (rapidly changing API, poor interaction with doc
> > tools, etc).
> 
> Are you referring to Zope 2 or 3 here?  I ask because I consider the 
> Zope 3 code (at least the parts written in the last couple years) to be 
> some of the best (externally) documented code I've worked with.

I'm talking about Zope 2.  I haven't had a chance to fully explore
Zope 3, yet, but what little I have learned has all been good.  I suspect
they are probably using an automatic documentation approach now?
That certainly seemed to be the way they've been leaning.

The biggest problem would seem to be the discontinuity between 2 & 3,
but that's also probably the biggest asset, so there you go. ;-)

Cheers,
Terry

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Bryan Olson]

A.M. Kuchling wrote:
 > Bryan Olson wrote:
 >
 >>I use dir() all the time; help() not so much. Typing help(help)
 >>shows:
 >>
 >> Help on _Helper in module site:
 >>
 >> Type help() for interactive help, or help(object) for help
 >> about object.
 >>
 >>That strikes me as not-particularly-helpful. Surely it should at
 >>least direct the user to 'pydoc.help'.
 >
 > help *is* pydoc.help, or at least a trivial wrapper around it, so I don't
 > see the purpose of mentioning that.

The purpose of mentioning it would be to, well, to tell the
user.

[...]
 > What additions to that string would you suggest?

Since "help *is* pydoc.help, or at least...", the call could
show the same thing as help(pydoc.help), or at least inform the
user that more of the story is available from help(pydoc.help).


 >>Three weeks ago, in trying to explain a point about Python's
 >>zlib module, I discovered that the doc was wrong.
 >>http://groups.google.com/group/comp.lang.python/msg/20609fff71a2ed02
 >
 > I don't think I'd change the Python docs to try to explain this,

How about to fix the error?

 > because I
 > have no confidence that we can get the details correct. BerkeleyDB, 
curses,
 > and the 'os' module pose similar problems.  For example, people sometimes
 > ask for more detail about POSIX functions, but no one wants to write a
 > Python-specific version of "Advanced Programming in the Unix 
Environment".

Options include copying doc from zlib.h, or telling the user to
look up the flags in the real doc.


-- 
--Bryan
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[A.M. Kuchling]

On Wed, 31 Aug 2005 12:14:35 GMT, 
> I use dir() all the time; help() not so much. Typing help(help)
> shows:
>
>  Help on _Helper in module site:
>
>  Type help() for interactive help, or help(object) for help
>  about object.
>
> That strikes me as not-particularly-helpful. Surely it should at
> least direct the user to 'pydoc.help'.

help *is* pydoc.help, or at least a trivial wrapper around it, so I don't
see the purpose of mentioning that.  The purpose of the wrapper is so naive
user can just type 'help' at an interpreter prompt:

>>> help
Type help() for interactive help, or help(object) for help about object.
>>>

What additions to that string would you suggest?

> Three weeks ago, in trying to explain a point about Python's
> zlib module, I discovered that the doc was wrong.
> http://groups.google.com/group/comp.lang.python/msg/20609fff71a2ed02

I don't think I'd change the Python docs to try to explain this, because I
have no confidence that we can get the details correct. BerkeleyDB, curses,
and the 'os' module pose similar problems.  For example, people sometimes
ask for more detail about POSIX functions, but no one wants to write a
Python-specific version of "Advanced Programming in the Unix Environment".  

--amk
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Bryan Olson]

Terry Hancock wrote:
 > Bryan Olson wrote:
 >
 >>I don't see any need to look beyond Python for a good example of
 >>poor documentation.  Are there serious Python programmers who
 >>don't constantly struggle with errors and omissions in the doc?
 >
 > Uh, yes, actually.
 >
 > IMHO, the available Python documentation is, extremely helpful,
 > concise and accessible.  Maybe you aren't using all of it:

A plausible theory. I have some possibly-illustrative examples
of what I ran into within the last few weeks.

 > 1) Remember that any object or module you load will tell you
 > its contents with a dir() or give you automatically generated
 > documentation with help().  This documentation has the advantage
 > of being almost always accurate and up-to-date, even if it is
 > sometimes too brief and poorly explained.

I use dir() all the time; help() not so much. Typing help(help)
shows:

 Help on _Helper in module site:

 Type help() for interactive help, or help(object) for help
 about object.

That strikes me as not-particularly-helpful. Surely it should at
least direct the user to 'pydoc.help'.


 > 2) More in-depth documentation for the Python standard library
 > is available in the "Library Reference".  This covers everything
 > from built-in functions to fairly obscure modules that are nevertheless
 > in the Python library.

Three weeks ago, in trying to explain a point about Python's
zlib module, I discovered that the doc was wrong.

http://groups.google.com/group/comp.lang.python/msg/20609fff71a2ed02

The Python standard library is certainly useful, but in my
opinion the bar is set too low.


 > 3) Questions about the functioning of the language are most accurately
 > resolved by trying them out in the interpreter. This is usually
 > faster than any documentation search.  Python's interpreter is extremely
 > friendly and easy to start up, so this is really easy to do.

Then how does one distinguish stable, supported services, from
incidental behavior that can change without notice?


 > 4) But if you want a more theoretical and explained version of the
 > language, there's always the "Language Reference".

Which is what steered me wrong on the behavior of slice objects:

   http://groups.google.com/group/comp.lang.python/msg/66014427182265b9

That one cost me a hours, mostly because when I my own code
misbehaves in certain cases, a language/doc bug is not my first
guess.


 > Between these 4 sources, I can resolve almost any question that
 > comes up about the core Python language.
 >
 > Somewhat more obscure applications are covered by the "Extending
 > and Embedding" document, and there are other documents and tutorials
 > either in your Python distribution (if you have a good one) or on
 > the http://www.python.org website).

Three days ago, I wanted to know how to call C from Python, and
the "Extending and Embedding" document told me:

 (I won't dwell on how to call the Python parser with a
 particular string as input -- if you're interested, have a
 look at the implementation of the -c command line option in
 Python/pythonmain.c from the Python source code.)

I got the Python source distribution, and couldn't find that
file. So I went to the CVS archive, and still couldn't find the
file. I don't think it exists. Had that doc just said nothing
about it, I probably would have found PyRun_SimpleString and its
siblings in a few minutes. I suspect the document is out of
date, as it also seems to teach the use of deprecated methods.

Whatever else one says about open-source documentation, keeping
it current is a major unsolved problem.


 > If you're really looking for cookbook examples, there are specific
 > websites to check for, though I usually just hit Google with a
 > few keywords.  And if all that fails you, you can always ask the
 > people on this list.

I'm with you on that. (I used to work for Google, where finding
the doc means eating the dog-food.) I find that for any popular
software, typing error messages into Google yields a better
results-to-effort ratio than trying to look them up in a manual.


 > I have NEVER seen a closed source application or programming
 > language that came with that much documentation and support.

I'm no fan of Microsoft, but in general, the Win32 API is far
better documented than is Python. (Just don't use the searching
facilities on the MSDev CD's to find the doc; Google it up.)

[...]
 > I also have to say, that as a module writer, Python's support
 > for self-documenting code or "literate programming" is excellent.
 > I'm really coming to appreciate the value of this.

Unfortunately, it's also full of traps.


-- 
--Bryan
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Michael Hudson]

"Adriaan Renting" <[EMAIL PROTECTED]> writes:

> The good commercial docs are better because there it is understood
> how important this is.

Also, they are probably written by people who are trained technical
writers which has to help at least a bit... writing good documentation
is hard.

Whether the Python documentation is good or bad depends on what you're
comparing it to.  It's probably not as good, say, as Apple's
documentation for Cocoa, but it could certainly be much, much worse.

Cheers,
mwh

-- 
  Enlightenment is probably antithetical to impatience.
-- Erik Naggum, comp.lang.lisp
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Sybren Stuvel]

Bryan Olson enlightened us with:
> I don't see any need to look beyond Python for a good example of
> poor documentation.  Are there serious Python programmers who don't
> constantly struggle with errors and omissions in the doc?

I don't have any problems with the documentation. It just works for
me. If you find any errors or omissions, fix them and send the
document maintainer an email. Why don't you help us by improving the
documentation?

Sybren
-- 
The problem with the world is stupidity. Not saying there should be a
capital punishment for stupidity, but why don't we just take the
safety labels off of everything and let the problem solve itself? 
 Frank Zappa
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Benji York]

Terry Hancock wrote:
> OTOH, there are lots of poorly-documented third-party Python
> modules (as in any language).  Zope is a particularly nasty
> example -- though I think I understand some of the reasons 
> behind that (rapidly changing API, poor interaction with doc
> tools, etc).

Are you referring to Zope 2 or 3 here?  I ask because I consider the 
Zope 3 code (at least the parts written in the last couple years) to be 
some of the best (externally) documented code I've worked with.
--
Benji York

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Terry Hancock]

On Tuesday 30 August 2005 02:32 am, Bryan Olson wrote:
> I don't see any need to look beyond Python for a good example of
> poor documentation.  Are there serious Python programmers who
> don't constantly struggle with errors and omissions in the doc?

Uh, yes, actually.

IMHO, the available Python documentation is, extremely helpful,
concise and accessible.  Maybe you aren't using all of it:

1) Remember that any object or module you load will tell you
its contents with a dir() or give you automatically generated
documentation with help().  This documentation has the advantage
of being almost always accurate and up-to-date, even if it is
sometimes too brief and poorly explained.

2) More in-depth documentation for the Python standard library
is available in the "Library Reference".  This covers everything
from built-in functions to fairly obscure modules that are nevertheless
in the Python library.

3) Questions about the functioning of the language are most accurately
resolved by trying them out in the interpreter. This is usually
faster than any documentation search.  Python's interpreter is extremely
friendly and easy to start up, so this is really easy to do.

4) But if you want a more theoretical and explained version of the
language, there's always the "Language Reference".

Between these 4 sources, I can resolve almost any question that
comes up about the core Python language.

Somewhat more obscure applications are covered by the "Extending
and Embedding" document, and there are other documents and tutorials
either in your Python distribution (if you have a good one) or on
the http://www.python.org website).

If you're really looking for cookbook examples, there are specific
websites to check for, though I usually just hit Google with a
few keywords.  And if all that fails you, you can always ask the
people on this list.

I have NEVER seen a closed source application or programming
language that came with that much documentation and support.

OTOH, there are lots of poorly-documented third-party Python
modules (as in any language).  Zope is a particularly nasty
example -- though I think I understand some of the reasons 
behind that (rapidly changing API, poor interaction with doc
tools, etc).

F. Lundh's documentation for Python Imaging Library is excellent,
though.

I also have to say, that as a module writer, Python's support
for self-documenting code or "literate programming" is excellent.
I'm really coming to appreciate the value of this.

I don't know, maybe I just don't have high expectations out
of documentation.  I've certainly made do with far worse
documentation than Python has.

Cheers,
Terry


--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Roel Schroeven]

Bryan Olson wrote:
> Adriaan Renting wrote:
> [...]
> 
>  > I do agree that a lot of OSS projects seem to lack somewhat in
>  > the documentation department, compared to a lot of commercial
>  > software. I would give the man page of gcc as an example, it's
>  > just one 6600 line blurb.
> 
> I don't see any need to look beyond Python for a good example of
> poor documentation.  Are there serious Python programmers who
> don't constantly struggle with errors and omissions in the doc?

There certainly are some areas where the documentation could be 
improved, but on the whole I think it's pretty good. I guess I'm not 
what you call a serious Python programmer, but still so far the 
documentation has provided answers to practically all questions I had.

> I don't mind the 6600 line blurb form, just so long as the info
> is there and is correct.

I agree. And on the whole I like manpages better than GNU's info system. 
info is good for providing background information and an overview of how 
everything works, but when I need a reference about command line options 
or config file settings, my experience is that I can find the needed 
information much easier in man pages.

-- 
If I have been able to see further, it was only because I stood
on the shoulders of giants.  -- Isaac Newton

Roel Schroeven
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Bryan Olson]

Adriaan Renting wrote:
[...]

 > I do agree that a lot of OSS projects seem to lack somewhat in
 > the documentation department, compared to a lot of commercial
 > software. I would give the man page of gcc as an example, it's
 > just one 6600 line blurb.

I don't see any need to look beyond Python for a good example of
poor documentation.  Are there serious Python programmers who
don't constantly struggle with errors and omissions in the doc?

I don't mind the 6600 line blurb form, just so long as the info
is there and is correct.


-- 
--Bryan
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Mike Meyer]

"Adriaan Renting" <[EMAIL PROTECTED]> writes:
> Marked -1 Flamebait, but I'll respond anyway.

Yup.

> I do agree that a lot of OSS projects seem to lack somewhat in the
> documentation department, compared to a lot of commercial software.

You know what? My experience is just the opposite. Commercial software
(at lest for Windows and OS X end user applications) often comes with
*no* documentation whatsoever. The few exceptions I've encountered
seldom installed it - if you wanted to look at it, you had to get the
distribution media and copy it by hand.

Instead, you get online help. While the latter is valuable, it's not a
substitute for good documentation.

 http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Paul Rubin]

"Adriaan Renting" <[EMAIL PROTECTED]> writes:
> He seems to think the GNU man pages are nice, but I find them very
> awkward as they have no hierarchical organization, and most miss examples.

The GNU man pages are an afterthought to meet expectations of Un*x
users who were used to man pages and the man command.  The good GNU
docs are in texinfo format, not man pages.  They have lots of examples
and they hierarchical structure and were designed to be navigated with
a pre-www hypertext browser or alternatively generate printed manuals.
These days there are also programs to render them as html so you can
navigate them with web browses.

> I do agree that a lot of OSS projects seem to lack somewhat in the
> documentation department, compared to a lot of commercial
> software. I would give the man page of gcc as an example, it's just
> one 6600 line blurb. The other part where a lot of OSS seems to be
> lacking is user interface design.

The man page only exists for the sake of users who insisted on having
a doc in that inferior format.  The "official" gcc doc is at:

   http://gcc.gnu.org/onlinedocs/gcc-4.0.1/gcc/

> The big question is: how to attract more doc writers to the OSS movement?

It's traditionally been a problem.  The FSF has hired a number of tech
writers over the years, and paid them to write docs.  That's one way.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Adriaan Renting]

Marked -1 Flamebait, but I'll respond anyway.

I've read the documents he refers to, and although I agree that the Python docs 
aren't perfect, I do not agree with him on which points. I for example do think 
it's important to incude info on which versions of the language support a 
feature.
He seems to think the GNU man pages are nice, but I find them very awkward as 
they have no hierarchical organization, and most miss examples.

I do agree that a lot of OSS projects seem to lack somewhat in the 
documentation department, compared to a lot of commercial software. I would 
give the man page of gcc as an example, it's just one 6600 line blurb. The 
other part where a lot of OSS seems to be lacking is user interface design.

I think the cause is that the OSS movement is almost solely comprised of 
programmers, while in a commercial environment there will be a lot of 
documentation writers and interface designers (and marketing, etc...)
I know I write my own documentation for the code I create, but I know I'll not 
do as good a job as a separate good doc writer would. In general I think the 
programmers should not write the documentation, and should not be the sole 
designers of the UI either.

The good commercial docs are better because there it is understood how 
important this is. I myself have always liked the Borland documentation a lot.

The big question is: how to attract more doc writers to the OSS movement?

Adriaan Renting.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: OpenSource documentation problems

[Rich Teer]

On Sat, 27 Aug 2005, Xah Lee wrote:

His usual crap.

  ___
  /|  /|  |  |
  ||__||  |  Please do   |
 /   O O\__ NOT  |
/  \ feed the|
   /  \ \ trolls |
  /   _\ \ __|
 /|\\ \ ||
/ | | | |\/ ||
   /   \|_|_|/   \__||
  /  /  \|| ||
 /   |   | /||  --|
 |   |   |// |  --|
  * _|  |_|_|_|  | \-/
   *-- _--\ _ \ //   |
 /  _ \\ _ //   |/
   *  /   \_ /- | - |   |
 *  ___ c_c_c_C/ \C_c_c_c

-- 
Rich Teer, SCNA, SCSA, OpenSolaris CAB member

President,
Rite Online Inc.

Voice: +1 (250) 979-1638
URL: http://www.rite-group.com/rich
-- 
http://mail.python.org/mailman/listinfo/python-list

OpenSource documentation problems

[Xah Lee]

previously i've made serious criticisms on Python's documentations
problems.
(see http://xahlee.org/perl-python/re-write_notes.html )

I have indicated that a exemplary documentation is Wolfram Research
Incorporated's Mathematica language. (available online at
http://documents.wolfram.com/mathematica/ )

Since Mathematica is a proprietary language costing over a thousand
dollars and most people in the IT industry are not familiar with it, i
like to announce a new discovery:

this week i happened to read the documentation of Microsoft's
JavaScript. See
http://msdn.microsoft.com/library/en-us/script56/html/js56jsconjscriptfundamentals.asp

This entire documentary is a paragon of technical writing. It has
clarity, conciseness, and precision. It does not abuse jargons, it
doesn't ramble, it doesn't exhibit author masturbation, and it covers
its area extremely well and complete. The documentation set are very
well organized into 3 sections: Fundamentals, Advanced, Reference. The
tutorial section “fundamentals” is extremely simple and to the
point. The “advanced” section gives a very concise yet easy to read
on some fine details of the language. And its language reference
section is complete and exact.

I would like the IT industry programers and the OpenSource fuckheads to
take note of this documentation so that you can learn.

Also, this is not the only good documentation in the industry. As i
have indicated, Mathematica documentation is equally excellent. In
fact, the official Java documentation (so-called Java API by Sun
Microsystems) is also extremely well-written, even though that Java the
language is unnecessarily very complex and involves far more technical
concepts that necessitate use of proper jargons as can be seen in their
doc.

A additional note i like to tell the OpenSource coding morons in the
industry, is that in general the fundamental reason that Perl, Python,
Unix, Apache etc documentations are extremely bad in multiple aspects
is because of OpenSource fanaticism. The fanaticism has made it that
OpenSource people simply became UNABLE to discern quality. This
situation can be seen in the responses of criticisms of OpenSource
docs. What made the situation worse is the OpenSource's mantra of
“contribution” — holding hostile any negative criticism unless
the critic “contributed” without charge.

Another important point i should point out is that the OpenSource
morons tend to attribute “lack of resources” as a excuse for their
lack of quality. (when they are kicked hard to finally admit that they
do lack quality in the first place) No, it is not lack of resources
that made the OpenSource doc criminally incompetent. OpenSource has
created tools that take far more energy and time than writing manuals.
Lack of resource of course CAN be a contribution reason, along with
OpenSource coder's general lack of ability to write well, among other
reasons, but the main cause as i have stated above, is OpenSource
fanaticism. It is that which have made them blind.

PS just to note, that my use of OpenSource here do not include Free
Software Foundation's Gnu's Not Unix project. GNU project in general
has very excellent documentation. GNU docs are geeky in comparison to
the commercial entity's docs, but do not exhibit jargon abuse,
rambling, author masturbation, or hodgepodge as do the OpenSource ones
mentioned above.

 Xah
 [EMAIL PROTECTED]
∑ http://xahlee.org/

-- 
http://mail.python.org/mailman/listinfo/python-list