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