Addendum to the Python doc problem at
http://www.python.org/doc/2.4.1/lib/module-os.path.html

I was working on a program where i needed to split a path into dirname,
corename, and suffix.

I came to this page and took me a while to understand what split() is
about. There are other path related functions splitext(), splitdrive(),
basename(), dirname(). User has to scan the whole page and read
painfully each one to fully understand how to choose and use them for
the task at hand.

As i have explained before (see references at bottom), documentation
should be organized oriented towards programer's tasks, not
alphabetically, compiler view, or computer sciency scheme. On this
os.path module, split(), splittext(), dirname(), basename() should all
be under one section. This way, their usefulness and each's fitness
becomes clearer, and also easier to document as a collective. Other
functions that test files or get info about files should be grouped
together. Don't be afraid of having functions that won't fit into some
grouping scheme. For exapmle, the walk() and
supports_unicode_filenames() can be lumped at the bottom as Other. The
need to present materials in some aloof, computer sciency, academic,
technically precise way is a major usability problem of the Python doc.

(the Pythoners's need to present materials in a formal style is a
backlash of the happy-go-lucky sloppiness of unix/perl community.
However, they being pretty much the same crowd without significant
critical thinking and writing skills, cannot do better by hiding in
formality.)

Also, at the top we see:

Warning: On Windows, many of these functions do not properly support
UNC pathnames. splitunc() and ismount() do handle them correctly.

As indicated before, this is a exhibition of tech geeking and
jargonizing. If this warning is necessary, place it at the bottom of
the page as a footnote. Also, spell out UNC, and provide a link to its
proper spec.

Tech geekers are very pretentious and cryptic in their tech docs. They
are afraid, as if spelling out UNC would make them unprofessional, that
their peers would deem them inferior. There are a myriad of technical
standards that any programer could only be familiar with a fraction,
confined to his area of expertise. Standards and its acronyms come and
go, and each with varying degrees of precision, actual relevance, and
they are intermingled with de facto “standards” in the commercial world
that may not even have official names. The tech geekers are clouded by
their tech-expertise. The purpose of documentation is not some cold
academic presentation. Vast majority who came to use os.path wouldn't
know what UNC is nor do they need to know. Spell things out when in
doubt.

UNC here, isn't really a significant “standard”. This warning should be
left out.

-----------
This post is archived at:
http://xahlee.org/perl-python/python_doc_os_path_split.html


☄