Here are some thoughts on reorganizing Python's documentation, with
one big suggestion.
The tutorial seems to be in pretty good shape because Raymond
Hettinger has been keeping it up to date. It doesn't cover
everything, but it's a solid introduction, and if people don't find it
works for them, they have lots of alternative books. No suggestions
here.
There are endless minor bugs in the library reference, but that seems
unavoidable. It documents many different and shifting modules, and
what to document is itself a contentious issue, so I don't think the
stream of small problems will ever cease.
There's another struggle within the LibRef: is it a reference or a
tutorial? Does it list methods in alphabetical order so you can look
them up, or does it list them in a pedagogically useful order? I
think it has to be a reference; if each section were to be a tutorial,
the manual would be huge. Here I think the solution is to encourage
separate tutorials and HOWTOs, and link to them from the LibRef.
The library reference has so many modules that the table of contents
is very large. Again, not really a problem that we can fix; splitting
it up into separate manuals doesn't seem like it would help.
The Extending/Embedding manual isn't great, but only advanced users
will come in contact with it, so I don't think it's a critical factor.
(Michael Hudson's new manual is a promising replacement.)
I suspect the Achilles' heel of the docs is the Language Reference.
Put aside the fact that it's not up to date with new-style classes and
other stuff; that would be fixable with some effort.
To some degree, the guide is trying to be very formal; it's written
like a specification for an implementor, not a document that people
would read through. But there's no other way for people to learn
about all the special object methods like __add__; the tutorial can't
cover them all, and the LibRef doesn't describe them. So the newbie
is stuck.
For example, I noticed this passing reference in Tim Bray's weblog: http://www.tbray.org/ongoing/When/200x/2005/08/27/Ruby
Based on first impressions and light exposure (a basis that
matters a lot) Ruby seems better-documented and easier to get
into than Python. I've actually written (a little)
production code in Python, but I always had the feeling that
there was lots of stuff going on I didn't understand; a
couple of days in, I think I have a better grasp on what
Ruby's up to, even where I'm not looking.
I don't know exactly what Bray meant, but suspect that a more readable
reference guide would have helped him understand what was going on.
Perhaps we need a friendlier counterpart to the RefGuide, something
like the 20-page introduction to Python at the beginning of Beazley's
Essential Reference:
* go over the statements one-by-one
* go over the basic types and their methods
* go over object semantics
* cover some of the lexical material in chapter 2 of the RefGuide
* overarching principles: go into a fair bit of detail, but
not every corner case; make the text readable, not meticulously
precise.
(I should point out: this suggestion is not entirely different from
some of the suggestions that X*h L** has made. He (?) makes his
suggestions in a venomous style, and with his own eccentric
terminology, but that doesn't mean he's always wrong, e.g. his
complaints about the re module's documentation are well-placed in the
main.)
One problem with such a friendly document: it might make the Ref Guide
even more irrelevant, if we always updated the friendly document
(which is easy) and left the RefGuide to drift even further out of
date (because it's hard to update). I don't know if this is an
argument for not having a friendly guide, or for dumping the RefGuide
entirely.
Dumping the RefGuide means there isn't a more formal-style description
of Python's semantics. I don't know if this matters. In theory, the
implementors of Jython or IronPython could be using the RefGuide to
know what they need to implement, but in practice I suspect
implementors use the test suite and existing library as checks. Maybe
we don't really need a tediously precise description of Python.
What do people think?
--amk 62 2341
A.M. Kuchling wrote: The tutorial seems to be in pretty good shape because Raymond Hettinger has been keeping it up to date. It doesn't cover everything, but it's a solid introduction, and if people don't find it works for them, they have lots of alternative books. No suggestions here.
The last time I looked at it, I thought the tutorial was the weakest
part of the documentation, because it assumed you were coming at Python
from another language, and often assumed that language was C. I mean,
the very first line says, "If you ever wrote a large shell script"...
which most people never have. The second page assumes you're using Unix
and throws in Windows as an afterthought. The third page demonstrates
string literals using the term "just as you would do in C". This is a
bit pointless because anyone familiar with C is probably bright enough
to make the connection for themselves, and anyone who isn't will not
appreciate what is being explained. This sort of theme continues
throughout.
Once upon a time I expect nearly all Python programmers came from C,
but today, I doubt that is true, especially since most universities
seem to prefer teaching Java over C++. In short, the tutorial is quite
outdated for today's prospective Python programmers. Admission: I once
offered to help clean it up, but by the time I got a reply from do**@python.org, I had started a new job and no longer had time. Sorry.
As for the alternative books comment, I think this is very wrong...
people are surely far more likely to buy a comprehensive reference to a
language they're already hooked on by a good tutorial, than they are to
buy an entry-level text for a language they don't quite understand but
which seems to boast good reference material!
There are endless minor bugs in the library reference, but that seems unavoidable. It documents many different and shifting modules, and what to document is itself a contentious issue, so I don't think the stream of small problems will ever cease.
Make the docs like PHP's docs. Users can post addendums and corrections
to the documentation, then all one of the official maintainers has to
do is fold in those corrections later.
There's another struggle within the LibRef: is it a reference or a tutorial? Does it list methods in alphabetical order so you can look them up, or does it list them in a pedagogically useful order? I think it has to be a reference; if each section were to be a tutorial, the manual would be huge.
I agree: reference foremost. However, all but the most trivial
libraries should have a short example, preferably on the first page of
their docs, so that you can quickly get an idea of whether this does
what you want it to do, and how the code is going to look. Some
libraries don't (ConfigParser comes to mind, Threading is another)
which make using them a bit of a chore to begin with. Again, if web
users could contribute examples as comments on the docs as with PHP,
they can be added in later.
The library reference has so many modules that the table of contents is very large. Again, not really a problem that we can fix; splitting it up into separate manuals doesn't seem like it would help.
Personally I'd be happy to see a lot of those modules removed from the
distribution, but I expect few will agree with me. ;)
--
Ben Sizer
A.M. Kuchling wrote: Here are some thoughts on reorganizing Python's documentation, with one big suggestion.
Thanks for bringing this up...
There are endless minor bugs in the library reference, but that seems unavoidable. It documents many different and shifting modules, and what to document is itself a contentious issue, so I don't think the stream of small problems will ever cease.
Since the topic of php.net-style comments comes up often, I thought I'd
note I've been working on a comment system: http://pythonpaste.org/comment/commentary/ -- this might be useful for
collecting and managing small updates and fixes to the documentation.
There's another struggle within the LibRef: is it a reference or a tutorial? Does it list methods in alphabetical order so you can look them up, or does it list them in a pedagogically useful order? I think it has to be a reference; if each section were to be a tutorial, the manual would be huge. Here I think the solution is to encourage separate tutorials and HOWTOs, and link to them from the LibRef.
We don't have a clear place to put that material. People's personal
pages leave the potential for material disappearing, and since that
stuff usually doesn't have a clear license we can't necessarily be sure
we can move it elsewhere if the original disappears or becomes out of
date. The Wiki would probably work, and maybe we should just say that
contributions on the Wiki are the preferred form for tutorials and
howtos. Then, of course, we have to link to them. With a commenting
system that can happen more organically.
The library reference has so many modules that the table of contents is very large. Again, not really a problem that we can fix; splitting it up into separate manuals doesn't seem like it would help.
There's a lot of dumb modules in there. I'd love if there was a module
index that excluded modules that were not useful. Like, say,
MimeWriter or flp. I think alphabetical or categorized doesn't matter
that much, compared to just a shorter list. Or maybe categorized, but
layed out so that it still all fits on one screen; the main library ToC
is simply too long because it doesn't fit on a screen, but the
categories can still be useful.
I suspect the Achilles' heel of the docs is the Language Reference. Put aside the fact that it's not up to date with new-style classes and other stuff; that would be fixable with some effort.
To some degree, the guide is trying to be very formal; it's written like a specification for an implementor, not a document that people would read through. But there's no other way for people to learn about all the special object methods like __add__; the tutorial can't cover them all, and the LibRef doesn't describe them. So the newbie is stuck.
Definitely; there's a problem for a newcomer, where the "language" is
documented one place (and hard to find), and the standard library
someplace else. As a newcomer it can be hard to know which is which.
Also, things like the functions in builtins are particularly hard to
find IMHO. I usually use pydoc for these things now, but not because I
particularly want to.
Perhaps we need a friendlier counterpart to the RefGuide, something like the 20-page introduction to Python at the beginning of Beazley's Essential Reference:
* go over the statements one-by-one * go over the basic types and their methods * go over object semantics * cover some of the lexical material in chapter 2 of the RefGuide * overarching principles: go into a fair bit of detail, but not every corner case; make the text readable, not meticulously precise.
I think that an example-based reference could be more useful than the
current layout. The corner cases *are* important, and it's valuable to
be able to read documentation to fully understand one particular
feature. Like, say, exceptions (which are undercovered right now).
But it can be easier to understand those with a series of examples
meant to demonstrate the behavior, than with a formal description.
One problem with such a friendly document: it might make the Ref Guide even more irrelevant, if we always updated the friendly document (which is easy) and left the RefGuide to drift even further out of date (because it's hard to update). I don't know if this is an argument for not having a friendly guide, or for dumping the RefGuide entirely.
Dumping the RefGuide means there isn't a more formal-style description of Python's semantics. I don't know if this matters. In theory, the implementors of Jython or IronPython could be using the RefGuide to know what they need to implement, but in practice I suspect implementors use the test suite and existing library as checks. Maybe we don't really need a tediously precise description of Python.
A test suite seems far more useful to implementors than any guide,
especially where the accuracy of that guide is not completely assured.
A series of examples seems more concrete than a formal description, and
as such can be not just more helpful, but also a more accurate in how
it transfers knowledge.
Ian Bicking wrote: There are endless minor bugs in the library reference, but that seems unavoidable. It documents many different and shifting modules, and what to document is itself a contentious issue, so I don't think the stream of small problems will ever cease.
Since the topic of php.net-style comments comes up often, I thought I'd note I've been working on a comment system: http://pythonpaste.org/comment/commentary/ -- this might be useful for collecting and managing small updates and fixes to the documentation.
Yes, do it the way php's documentation is done, Xah Lee's recent trolls
aside.
Ben> Make the docs like PHP's docs.
Easier said than done. There is still - I think - a project in the works to
redo the python.org website, but I have no idea if it means to retain
ht2html+latex2html as the page builders or move to something else. Neither
ht2html nor latex2html support in inline annotation feature. It would need
to be added.
What was the comment here the other day? Python has more web application
frameworks than keywords. PHP only has one. ;-)
Skip
Ian> A test suite seems far more useful to implementors than any guide,
Of course, test cases can be modified or ignored. I'd agree with you if we
had a test suite that was more strongly cast in stone.
Skip
Ian Bicking wrote: There's another struggle within the LibRef: is it a reference or a tutorial? Does it list methods in alphabetical order so you can look them up, or does it list them in a pedagogically useful order? I think it has to be a reference; if each section were to be a tutorial, the manual would be huge. Here I think the solution is to encourage separate tutorials and HOWTOs, and link to them from the LibRef.
We don't have a clear place to put that material. People's personal pages leave the potential for material disappearing
so ? this "if we don't own it, we won't even pretend it exists" attitude
of the PSF is beginning to get a bit boring.
(the standard library suffers from the same problem)
</F>
>> A series of examples seems more concrete than a formal description,<<
Amen. This is why people buy the books: The good ones have lots of
examples. The wizards glance at them in passing and think, "Duh." And
the rest of us (including the intermediate folks, I'll bet) are
grateful for the chance to see a real live example.
rd
Fredrik Lundh wrote: There's another struggle within the LibRef: is it a reference or a tutorial? Does it list methods in alphabetical order so you can look them up, or does it list them in a pedagogically useful order? I think it has to be a reference; if each section were to be a tutorial, the manual would be huge. Here I think the solution is to encourage separate tutorials and HOWTOs, and link to them from the LibRef.
We don't have a clear place to put that material. People's personal pages leave the potential for material disappearing
so ? this "if we don't own it, we won't even pretend it exists" attitude of the PSF is beginning to get a bit boring.
Well, I ain't the PSF, so my comment here doesn't really indicate
anything with respect to that. There are already links in the
reference document to external documents. But if we start getting a
half dozen links for each page (which is not an unreasonable number)
the maintenance of trimming dead links and pages that are out of date
becomes more significant. And there's no particular coordination, or
any simple feedback process that can be applied to all content.
I don't think there should be any policy discouraging external links;
there's a lot of sources like the Python Cookbook, some free online
books (e.g., Dive Into Python, or Think Like A Computer Scientist), and
stable personal pages that should be linked in . But I do think that
we should encourage some specific process for new or revised
tutorial/howto contributions, like encouraging people put such material
in the wiki.
Ian A series of examples seems more concrete than a formal description,<<
rd> Amen. This is why people buy the books: The good ones have lots of
rd> examples. The wizards glance at them in passing and think, "Duh."
rd> And the rest of us (including the intermediate folks, I'll bet) are
rd> grateful for the chance to see a real live example.
ISTR that comment was made in reference to the Language Reference, which as
written is intended for "language lawyers". Examples there seem
counterproductive.
Skip
On 6 Dec 2005 10:10:09 -0800,
Ian Bicking <ia**@colorstudy.com> wrote: stable personal pages that should be linked in . But I do think that we should encourage some specific process for new or revised tutorial/howto contributions, like encouraging people put such material in the wiki.
To this end, I've moved the howtos off their separate SourceForge
project, and into Doc/howto in Python SVN. The sorting howto seemed
small enough and incomplete enough that it would be better as a wiki.
There's another small one, doanddont.tex, that might also be good as a
wiki page. I'm currently not planning to convert any of the larger
documents, such as the curses or regex ones, to wiki format.
--amk sk**@pobox.com wrote: Ian> A test suite seems far more useful to implementors than any guide,
Of course, test cases can be modified or ignored. I'd agree with you if we had a test suite that was more strongly cast in stone.
hum. a test suite like that would have to be constructed very carefully.
The current CPython testsuite tests quite some things that are obviously
implementation details. For example test_itertools.py checks that izip
reuses tuples (which means changing them) when the refcount is 1. This
is something which does not quite work in an implementation using a
different GC :-)
Although on the other hand a short poll revealed that the reference
manual was not considered to be the most useful source among the PyPy
developpers :-)
Cheers,
Carl Friedrich Bolz
In article <ma***************************************@python. org>,
A.M. Kuchling <am*@amk.ca> wrote: There's another struggle within the LibRef: is it a reference or a tutorial? Does it list methods in alphabetical order so you can look them up, or does it list them in a pedagogically useful order? I think it has to be a reference; if each section were to be a tutorial, the manual would be huge. Here I think the solution is to encourage separate tutorials and HOWTOs, and link to them from the LibRef.
Here's a question that kind of gets to the heart of a lot of the
problem: where does ``print`` get documented? If we can come up with a
good process for answering that question, we can probably fix a lot of
other problems. (Note emphasis on the word "process".)
--
Aahz (aa**@pythoncraft.com) <*> http://www.pythoncraft.com/
"Don't listen to schmucks on USENET when making legal decisions. Hire
yourself a competent schmuck." --USENET schmuck (aka Robert Kern) Of course, test cases can be modified or ignored. I'd agree with you if we had a test suite that was more strongly cast in stone.
Carl> hum. a test suite like that would have to be constructed very
Carl> carefully. The current CPython testsuite tests quite some things
Carl> that are obviously implementation details.
No disagreement there. The current CPython test suite would not cut the
mustard as a test for Python specification compliance.
Skip
Aahz wrote: Here's a question that kind of gets to the heart of a lot of the problem: where does ``print`` get documented? If we can come up with a good process for answering that question, we can probably fix a lot of other problems. (Note emphasis on the word "process".)
Good point; the language reference and the tutorial is the only place
we currently keep this kind of documentation, and neither provides the
kind of reference that new users need. I'd also note that the
distinction between builtins and syntax isn't meaningful to a new user.
So, for instance, that "exec" and "eval" are documented in very
different places is confusing. And that the "print" statement and the
"write" method are also differently placed.
I think it would be very useful if there was reference (not just
tutorial) documentation for all the syntax, special semantics like
magic methods, and all the functions and objects in builtins. To a new
user these are all the same thing. Even to an experienced users these
are all about the same thing. I don't think such a document would be
all that long or hard to write.
On a usability note, I'd want every name a user might encounter to show
up in an index or table of contents. Basically all the keywords, magic
methods, exceptions, builtin functions, builtin types, and at least
somewhere the methods of builtin types should also be available.
Carl Friedrich Bolz wrote: sk**@pobox.com wrote:
Ian> A test suite seems far more useful to implementors than any guide,
Of course, test cases can be modified or ignored. I'd agree with you if we had a test suite that was more strongly cast in stone.
hum. a test suite like that would have to be constructed very carefully. The current CPython testsuite tests quite some things that are obviously implementation details. For example test_itertools.py checks that izip reuses tuples (which means changing them) when the refcount is 1. This is something which does not quite work in an implementation using a different GC :-)
Although on the other hand a short poll revealed that the reference manual was not considered to be the most useful source among the PyPy developpers :-)
True, but the choice is between abandoning it or updating it.
I would vote for the latter.
Colin W. Cheers,
Carl Friedrich Bolz
Ian> I think it would be very useful if there was reference (not just
Ian> tutorial) documentation for all the syntax, special semantics like
Ian> magic methods, and all the functions and objects in builtins.
It's pretty common to have a User's Guide as well as a Reference Manual for
many applications. Python has always lacked a User's Guide.
I find it hard to imagine any one person having the time to simply sit down
and bat out such a tome though. I'm partial to using wikis as collaborative
environments. (They more readily admit a group of people to the process
without a formal registration process as would doing the whole thing via
Python's svn repository.) Creating a UsersGuide section of the Python wiki
with reST as the markup might be a good place to work on such a beast with
the goal that it would be a stepping stone to a more standalone document.
Skip sk**@pobox.com wrote: Ian> I think it would be very useful if there was reference (not just Ian> tutorial) documentation for all the syntax, special semantics like Ian> magic methods, and all the functions and objects in builtins.
It's pretty common to have a User's Guide as well as a Reference Manual for many applications. Python has always lacked a User's Guide.
I find it hard to imagine any one person having the time to simply sit down and bat out such a tome though. I'm partial to using wikis as collaborative environments. (They more readily admit a group of people to the process without a formal registration process as would doing the whole thing via Python's svn repository.) Creating a UsersGuide section of the Python wiki with reST as the markup might be a good place to work on such a beast with the goal that it would be a stepping stone to a more standalone document.
Skip
Most of the issues regarding issues like where to "print" and
"sys.write", etc results from a wrong assumtion: that the
Lang ref as only for "language lawyers". My sense is the
many people see the Lang ref as a Syntax manual. It doesn't
have to be only that.
My suggestions:
- Keep the basic organization of the Lang Ref the same
but make the entries more accessible to people new to
Python. If is a reference, keep the BNF, details, etc.
Add (brief, terse!) explanatory material where confusion
may occur. Add examples!! (not 1 in 10000 writers can
write clearly enough to do without examples)
- Move Section 2 (builtin types) from the Lib Ref to the
Lang Ref. This section documents data types, builtin
objects, methods, etc. These are all language things,
not library things.
- Distinction between Lib and Lang is easy: if you import
it, it goes in Lib. otherwise it's in Lang. (If it ain't got ints,
string, None, etc, it ain't the python language. It could be
python without pprint.)
- Make an exception for sys (document in both, or maybe
full doc in Lib, enough doc in Lang to support the needed
references in Lang, or maybe all in Lang as an exception?)
If the Lang ref is made a ref for the language, the
Lib ref for the library, make them both accessible, then
they both get used as they should.
To me, the difference between tutorial and reference is:
Organization:
+ Ref: organised depth-first. Each topic is treated fully
(in complete depth) before the next.
+ Tut: organised breadth-first: broad sweeps are made
accross the subject matter, then again a greater death,
then again, etc.
Audience:
+ Ref: material in a section can assume knowlage level
determined by the material. (description of metaclass
stuff can assume user knows basics of class stuff.)
+ Tut: Knowlage level assumed depends on material's
position in the doc (assumes knowlage of previously
presented material.)
Purpose:
+ Tut: Teach the language to a user.
+ Ref: Allow the user to find out information about the language
Style:
+ Tut: Often chatty: "Now that we've seen how iterators
work, lets put that to work"
+ Ref: Terse: "examples:" (but not TOO terse. Idea is to
transfer info to reader as effectively a possible. If it takes
reader (of the assumed level) 5 minutes of thinking to
say "oh, now I see" something's wrong.)
Both tutorial material and reference material are desirable but
if resources allow only one reference is better.
A user guide would be great but just an update of the tutorial
and some reorganiztion and expansion of the two primary
references would improve things a lot in the interim.
(sorry for the rough shape this posting is but I've got to run.)
You are correct about the tutorial. Just try to look at the home page
through the eyes of a curious Windows user who wants to learn
programming and is trying to decide whether to take up Perl, Ruby,
Python, or Visual Basic, let's say.
On the home page, the first link that catches the eye for this user is:
"Beginner's Guide to Programming - <bold> start here if you're new to
programming </bold>." That's me. Click.
Now you are on a page with promising-looking links that all start with
"BeginnersGuide," but the first three are not warm welcomes, they are
housekeeping matters about where you can take courses or how to
download Python for people who don't know whether they want to or not
yet, or there's one that says "examples" which will take you to the
ActiveState Cookbook site so you can get really confused.
Then you hit the link that says "BeginnersGuide/Nonprogrammers" Ah!
That's me. <click>
The first prominent link says: "Python Tutorial" along with a notice at
the top of the page that tells you if you've never programmed before
this is the page for you.
Click on Python Tutorial. Some official business to start off. Then you
see, "Whetting Your Appetite" Ah, I am ready for that. <click>
The first sentence reads:
"If you ever wrote a large shell script, you probably know this
feeling: you'd love to add yet another feature, but it's already so
slow, and so big, and so complicated; or the feature involves a system
call or other function that is only accessible from C ...Usually the
problem at hand isn't serious enough to warrant rewriting the script in
C; perhaps the problem requires variable-length strings or other data
types (like sorted lists of file names) that are easy in the shell but
lots of work to implement in C, or perhaps you're not sufficiently
familiar with C."
Most of the site has been laid out by programmers, for programmers, who
apparently want to keep it that way, based upon what I've seen.
Aahz wrote: Here's a question that kind of gets to the heart of a lot of the problem: where does ``print`` get documented? If we can come up with a good process for answering that question, we can probably fix a lot of other problems. (Note emphasis on the word "process".)
Sometimes a poor or missing process can be supplemented with improved
technology. If the prospective audience can always answer the question
"where _was_ ``print`` documented?" it would somewhat lessen the
importance of having said good process.
I mention this (admittedly obvious) point only because (a) sometimes
debates about process are fruitless, and (b) having _both_ would fix
even more problems than just having a good process.
-Peter
A.M. Kuchling wrote: Here are some thoughts on reorganizing Python's documentation, with one big suggestion.
Throwing in my own 2¢.. I think the language reference should be
disseminated into the rest of the documentation. Some of the stuff
(operator precedence anybody?) could be done directly, while more
technical aspects could be put in boxes with green[0] backgrounds
saying "technical details". Thinks specific to one implementation
could further be given a blue[0] background.
I don't expect everything to make the transition. Are discussions of
"atoms" and fragments of BNF really better than calling them
expressions and linking to CPython's Grammar file?
--
Adam Olsen, aka Rhamphoryncus
[0] Colors pulled off the top of my head
BartlebyScrivener wrote: You are correct about the tutorial. Just try to look at the home page through the eyes of a curious Windows user who wants to learn programming and is trying to decide whether to take up Perl, Ruby, Python, or Visual Basic, let's say.
On the home page, the first link that catches the eye for this user is: "Beginner's Guide to Programming - <bold> start here if you're new to programming </bold>." That's me. Click.
Now you are on a page with promising-looking links that all start with "BeginnersGuide," but the first three are not warm welcomes, they are housekeeping matters about where you can take courses or how to download Python for people who don't know whether they want to or not yet, or there's one that says "examples" which will take you to the ActiveState Cookbook site so you can get really confused.
Then you hit the link that says "BeginnersGuide/Nonprogrammers" Ah! That's me. <click>
The first prominent link says: "Python Tutorial" along with a notice at the top of the page that tells you if you've never programmed before this is the page for you.
Click on Python Tutorial. Some official business to start off. Then you see, "Whetting Your Appetite" Ah, I am ready for that. <click>
The first sentence reads:
"If you ever wrote a large shell script, you probably know this feeling: you'd love to add yet another feature, but it's already so slow, and so big, and so complicated; or the feature involves a system call or other function that is only accessible from C ...Usually the problem at hand isn't serious enough to warrant rewriting the script in C; perhaps the problem requires variable-length strings or other data types (like sorted lists of file names) that are easy in the shell but lots of work to implement in C, or perhaps you're not sufficiently familiar with C."
Most of the site has been laid out by programmers, for programmers, who apparently want to keep it that way, based upon what I've seen.
I think the Python community as a whole should take this on board as
fair criticism. It would be really nice if a total beginner did actually
see a usable path through the web to their first working Python program.
regards
Steve
--
Steve Holden +44 150 684 7255 +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/
Adam> I don't expect everything to make the transition. Are discussions
Adam> of "atoms" and fragments of BNF really better than calling them
Adam> expressions and linking to CPython's Grammar file?
Actually, yes. The actual Grammar file isn't designed for explanation
(mostly it's more complex, but it also has extra productions) and is
somewhat (maybe a lot) different than the BNF in the ref manual.
Skip
> The library reference has so many modules that the table of contents is very large. Again, not really a problem that we can fix; splitting it up into separate manuals doesn't seem like it would help.
I like the Global Module Index in general - it allows quick access to
exactly what I want.
I would like a minor change to it though - stop words starting with a
given letter rolling over to another column (for example, os.path is at
the foot of one column, while ossaudiodev is at the head of the next),
and provide links to each initial letter at the top of the page.
Iain The library reference has so many modules that the table of contents is very large. Again, not really a problem that we can fix; splitting it up into separate manuals doesn't seem like it would help.
Iain> I like the Global Module Index in general - it allows quick access
Iain> to exactly what I want. I would like a minor change to it though
Iain> - stop words starting with a given letter rolling over to another
Iain> column (for example, os.path is at the foot of one column, while
Iain> ossaudiodev is at the head of the next), and provide links to each
Iain> initial letter at the top of the page.
I know it's not what you asked for, but give http://staging.musi-cal.com/modindex/
a try. See if by dynamically migrating the most frequently requested
modules to the front of the section it becomes more manageable.
Skip sk**@pobox.com wrote: The library reference has so many modules that the table of contents >> is very large. Again, not really a problem that we can fix; >> splitting it up into separate manuals doesn't seem like it would >> help.
Iain> I like the Global Module Index in general - it allows quick access Iain> to exactly what I want. I would like a minor change to it though Iain> - stop words starting with a given letter rolling over to another Iain> column (for example, os.path is at the foot of one column, while Iain> ossaudiodev is at the head of the next), and provide links to each Iain> initial letter at the top of the page.
I know it's not what you asked for, but give
http://staging.musi-cal.com/modindex/
a try. See if by dynamically migrating the most frequently requested modules to the front of the section it becomes more manageable.
Skip
Well, the point of the GMI is to lookup whatever module you are
currently having to use for the first time (at least it is for me).
Giving easy access to the modules I've already had to look up (because
they are common) doesn't really help - I've already accessed those.
It'll be nice when I have to find some obscure feature I haven't used
in them before, but really, all I'd like is an easy to use index :)
Iain
On 12/7/05, sk**@pobox.com <sk**@pobox.com> wrote: Adam> I don't expect everything to make the transition. Are discussions Adam> of "atoms" and fragments of BNF really better than calling them Adam> expressions and linking to CPython's Grammar file?
Actually, yes. The actual Grammar file isn't designed for explanation (mostly it's more complex, but it also has extra productions) and is somewhat (maybe a lot) different than the BNF in the ref manual.
IMO the only people who are going to appreciate BNF used for
explanation are those working on language implementations, and they'll
need to understand the Grammar file anyway. The rest of us need a
simpler explanation involving examples.
Having a large and detailed language specification, although an
admirable ideal, is a waste of time when the target audience is
perhaps a few dozen people. Make it useful for everybody and it'll be
worth maintaining.
--
Adam Olsen, aka Rhamphoryncus
Iain> Well, the point of the GMI is to lookup whatever module you are
Iain> currently having to use for the first time (at least it is for
Iain> me). Giving easy access to the modules I've already had to look
Iain> up (because they are common) doesn't really help - I've already
Iain> accessed those. It'll be nice when I have to find some obscure
Iain> feature I haven't used in them before, but really, all I'd like is
Iain> an easy to use index :)
Reorganizing the global module index isn't all that straightforward. It is
generated by latex2html. To change its layout would probaly require some
additional markup and mods to latex2html (not a pretty piece of code as I
understand it).
OTOH, I find myself returning to the same module docs over and over again to
look up function arguments, regular expression syntax, that sort of thing.
Having to page down past dozens and dozens of modules I don't care about to
click on "sys" or "datetime" motivated me to write my little hack.
Skip
Adam> Having a large and detailed language specification, although an
Adam> admirable ideal, is a waste of time when the target audience is
Adam> perhaps a few dozen people.
Just because that audience is small doesn't mean they are unimportant.
There are currently four actively maintained/developed implementations of
Python. A common language reference manual is important for them, and
indirectly for the people who use the four implementations.
I'm not trying to discount the value of a good Users Guide.
Skip sk**@pobox.com wrote: Iain> Well, the point of the GMI is to lookup whatever module you are Iain> currently having to use for the first time (at least it is for Iain> me). Giving easy access to the modules I've already had to look Iain> up (because they are common) doesn't really help - I've already Iain> accessed those. It'll be nice when I have to find some obscure Iain> feature I haven't used in them before, but really, all I'd like is Iain> an easy to use index :)
Reorganizing the global module index isn't all that straightforward. It is generated by latex2html. To change its layout would probaly require some additional markup and mods to latex2html (not a pretty piece of code as I understand it).
OTOH, I find myself returning to the same module docs over and over again to look up function arguments, regular expression syntax, that sort of thing. Having to page down past dozens and dozens of modules I don't care about to click on "sys" or "datetime" motivated me to write my little hack.
Skip
Argh, you made me look at the html again - at least now I know *why* it
is so disgusting. I understand there's a new version coming out soon,
hopefully in html 4 strict or xhtml. I'm sure at that point it'll be
easier to use. I can wait. :)
Iain
On 12/7/05, sk**@pobox.com <sk**@pobox.com> wrote: Adam> Having a large and detailed language specification, although an Adam> admirable ideal, is a waste of time when the target audience is Adam> perhaps a few dozen people.
Just because that audience is small doesn't mean they are unimportant. There are currently four actively maintained/developed implementations of Python. A common language reference manual is important for them, and indirectly for the people who use the four implementations.
What I meant is that a small audience is not going to draw enough
attention to get the effort it requires. I agree absolutely that the
material it contains is important. That's why I feel it should be
merged with the other documents, to ensure that it really does get
maintained.
--
Adam Olsen, aka Rhamphoryncus sk**@pobox.com wrote: Iain> I like the Global Module Index in general - it allows quick access Iain> to exactly what I want. I would like a minor change to it though Iain> - stop words starting with a given letter rolling over to another Iain> column (for example, os.path is at the foot of one column, while Iain> ossaudiodev is at the head of the next), and provide links to each Iain> initial letter at the top of the page.
I know it's not what you asked for, but give
http://staging.musi-cal.com/modindex/
a try. See if by dynamically migrating the most frequently requested modules to the front of the section it becomes more manageable.
That's pretty cool. What I don't know is how it would look after
thousands of people using it. I know that I probably only have 10
modules or so that I consistently need to check the docs for. Your hack
above would conveniently place those all at the top if I was the only
user. But are those 10 modules the same 10 modules that other folks
need? I don't know...
Of course, the only way to find out is to try...
STeVe
A.M. Kuchling wrote: There's another struggle within the LibRef: is it a reference or a tutorial? Does it list methods in alphabetical order so you can look them up, or does it list them in a pedagogically useful order? I think it has to be a reference; if each section were to be a tutorial, the manual would be huge. Here I think the solution is to encourage separate tutorials and HOWTOs, and link to them from the LibRef.
I actually like the conversational, tutorial style the current LibRef
has -- in fact I consider that style one of the Python Docs strengths.
All too often I see manuals that consist of only fuction by fuction &
class by class breakdowns. That's fine if the module is just a
collection of independant functions, but falls short whenever you want
to use multiple functions & classes in a module together. Function by
function documentation tends to ignore the "big picture," how all the
functions & classes work together, and the philosophy behind their use.
*That's* what I feel it is important to document - if I want to know
parameters, return values and side-effects, I'll just look at the doc
strings.
Certainly you could go for the User Manual/Reference Manual dichotomy,
but in my experience, the User Manual tends to get short shrift - the
experts writing it tend to think that it's just for "n00bs", and leave
out the complex and esoteric items, thinking that the Reference Manual
suffices. Unfortunately, the background and philosophy are needed *more*
for the complex/esoteric functions than for the simple ones, merely
because you're less likely to understand them from a "takes a,b,c, sets
the froz flag, and returns x,y,z" type description.
And to expand on what Michael Spencer said, a lot of the time when I'm
digging throught the LibRef, I'm looking for a module that'll help me do
'X'. Most of the "Reference Manuals" I've seen tend to assume you know
what fuction you're looking for, and don't give you any direction in the
forest of function descriptions. With the current tone/level and
categorical grouping of the LibRef, it's easy to browse through and look
for things that might help (at least easier than it would be with, say,
a strict alphabetical list).
In article <ma***************************************@python. org>,
<sk**@pobox.com> wrote: OTOH, I find myself returning to the same module docs over and over again to look up function arguments, regular expression syntax, that sort of thing. Having to page down past dozens and dozens of modules I don't care about to click on "sys" or "datetime" motivated me to write my little hack.
That's why I use Lynx! ;-) ("/]re" takes me right to regex docs)
--
Aahz (aa**@pythoncraft.com) <*> http://www.pythoncraft.com/
"Don't listen to schmucks on USENET when making legal decisions. Hire
yourself a competent schmuck." --USENET schmuck (aka Robert Kern)
Steve Holden wrote: BartlebyScrivener wrote: Now you are on a page with promising-looking links that all start with "BeginnersGuide," but the first three are not warm welcomes, they are housekeeping matters about where you can take courses or how to download Python for people who don't know whether they want to or not yet, or there's one that says "examples" which will take you to the ActiveState Cookbook site so you can get really confused.
<snip many more valid criticisms>
I think the Python community as a whole should take this on board as fair criticism. It would be really nice if a total beginner did actually see a usable path through the web to their first working Python program.
OK I'll bite. That Beginners Guide page has bugged me for a long time.
It's a wiki page but it is marked as immutable so I can't change it.
Here are some immediate suggestions:
- get rid of the 1-7 list at the top it is very confusing and does not
present information in a useful form or order. All of these links except
the help link appear in the body text in more useful form.
- Change the sentence "Read BeginnersGuide/Overview to learn the key
points." to "Read BeginnersGuide/Overview to learn what makes Python
special." Or maybe get rid of it completely - I'm not sure evangelism
belongs on this page.
- Add a sentence at the end of the paragraph that starts, "Once you've
read a tutorial" that says, "Many other resources are listed in
BeginnersGuide/Help."
On the BeginnersGuide/NonProgrammers page, I agree, Guido's tutorial
probably shouldn't be listed first even with the disclaimer. It goes way
to fast for a beginner. Alan Gauld's tutorial is very popular on the
tutor list, so is A Byte of Python (which is not listed on the
NonProgrammers page). I would list them first. Or maybe take a vote on
the tutor list for favorite beginner's tutorial.
That should help a little, maybe we won't confuse the newbies before
they even get to an interpreter prompt.
Kent
PS I am aware of the usual SF bug report procedure for docs, does it
apply to these pages? I don't know, they don't have the usual "About
this document" link at the bottom. I'm happy to submit a patch if that
will help. Otherwise I'm not sure what "the Python community as a whole
[taking] this on board" should look like. http://staging.musi-cal.com/modindex/
Steven> What I don't know is how it would look after thousands of people
Steven> using it. I know that I probably only have 10 modules or so
Steven> that I consistently need to check the docs for. Your hack above
Steven> would conveniently place those all at the top if I was the only
Steven> user. But are those 10 modules the same 10 modules that other
Steven> folks need? I don't know...
Is suspect most people need help with a fairly common module subset on a
regular basis. This won't provide a cache with a 100% hit rate, but the
cost of a cache miss isn't all that high. Also, you might discover some
useful modules you hadn't used before simply because they are frequently
referenced.
Skip
Yep, Guido's tutorial belongs on the Python for Programmers page where
people know who he is and are able to understand him. Alan Gauld's tutorial is very popular on the tutor list, so is A Byte of Python (which is not listed on the NonProgrammers page). I would list them first. Or maybe take a vote on the tutor list for favorite beginner's tutorial.
And perhaps How To Think Like A Computer Scientist. Then maybe
introduce them with a single sentence like:
"Python is so easy to learn and immediately useful that many popular
tutorials use Python to teach computer programming."
Kent> OK I'll bite. That Beginners Guide page has bugged me for a long
Kent> time. It's a wiki page but it is marked as immutable so I can't
Kent> change it.
That's because for some reason it is one of the top two or three most
frequently defaced pages on the wiki. We got tired of having to revert
changes to it every day or two. I'll take a look at incorporating your
suggestions.
Skip
Might be better as:
"Many popular tutorials use Python to teach computer programming,
because Python is free, easy to learn, immediately useful, and fun!"
Steven Bethard <st************@gmail.com> writes: sk**@pobox.com wrote: Iain> I like the Global Module Index in general - it allows quick access Iain> to exactly what I want. I would like a minor change to it though Iain> - stop words starting with a given letter rolling over to another Iain> column (for example, os.path is at the foot of one column, while Iain> ossaudiodev is at the head of the next), and provide links to each Iain> initial letter at the top of the page.
I know it's not what you asked for, but give
http://staging.musi-cal.com/modindex/
a try. See if by dynamically migrating the most frequently requested modules to the front of the section it becomes more manageable.
That's pretty cool. What I don't know is how it would look after thousands of people using it. I know that I probably only have 10 modules or so that I consistently need to check the docs for. Your hack above would conveniently place those all at the top if I was the only user. But are those 10 modules the same 10 modules that other folks need? I don't know...
Of course, the only way to find out is to try...
Or you can just look up the module you need to write a 'bot to
constantly look up the docs for your favorite 10 modules. . . .
--
Mark Jackson - http://www.alumni.caltech.edu/~mjackson
If it made sense, that would be a very powerful idea.
- Bruce Eric Kaplan
On Wed, 7 Dec 2005 07:45:13 -0600, sk**@pobox.com <sk**@pobox.com> wrote: Just because that audience is small doesn't mean they are unimportant. There are currently four actively maintained/developed implementations of Python. A common language reference manual is important for them, and indirectly for the people who use the four implementations.
They're not unimportant, but I don't think the reference manual *is*
important to them because they've gotten this far with an outdated
one; the code may be resource enough. This is why I think that the
effort expended to update a document aimed at them might be better
spent on something more widely useful.
I remembered another problem from the weekend with documenting
new-style classes. It seemed reasonable to begin with PEP 252, and
see if any bits of the PEP can be migrated into the RefGuide, but then
I found this comment in the abstract:
[Editor's note: the ideas described in this PEP have been
incorporated into Python. The PEP no longer accurately
describes the implementation.]
So now we're *really* stuck. The RefGuide doesn't describe the rules;
the PEP no longer describes them either; and probably only Guido can
write the new text for the RefGuide. (Or are the semantics the same
and only some trivial details are different?)
--amk
In article <x9********************@speakeasy.net>,
A.M. Kuchling <am*@amk.ca> wrote: So now we're *really* stuck. The RefGuide doesn't describe the rules; the PEP no longer describes them either; and probably only Guido can write the new text for the RefGuide. (Or are the semantics the same and only some trivial details are different?)
Raymond Hettinger (and/or maybe one of the metaclass wizards) can
probably also write it, with Guido editing after. That might produce
even more accuracy in the end.
--
Aahz (aa**@pythoncraft.com) <*> http://www.pythoncraft.com/
"Don't listen to schmucks on USENET when making legal decisions. Hire
yourself a competent schmuck." --USENET schmuck (aka Robert Kern)
Adam Olsen wrote: On 12/7/05, sk**@pobox.com <sk**@pobox.com> wrote: Adam> I don't expect everything to make the transition. Are discussions Adam> of "atoms" and fragments of BNF really better than calling them Adam> expressions and linking to CPython's Grammar file?
Actually, yes. The actual Grammar file isn't designed for explanation (mostly it's more complex, but it also has extra productions) and is somewhat (maybe a lot) different than the BNF in the ref manual.
IMO the only people who are going to appreciate BNF used for explanation are those working on language implementations, and they'll need to understand the Grammar file anyway. The rest of us need a simpler explanation involving examples.
Having a large and detailed language specification, although an admirable ideal, is a waste of time when the target audience is perhaps a few dozen people. Make it useful for everybody and it'll be worth maintaining.
A language reference manual and a language specification
are two different things, and the existence of bnf/grammar info
in a language reference manual need to turn it into some
inpenaterable ISO-spec like document.
I know that I sometimes want to know if some unusual syntax
is legal or not, particularly when learning a language. The
bnf/grammar stuff is relatively small and if sections are
organised consistently, easily skipped over by readers with
no interest it it. sk**@pobox.com wrote: The library reference has so many modules that the table of contents >> is very large. Again, not really a problem that we can fix; >> splitting it up into separate manuals doesn't seem like it would >> help.
Iain> I like the Global Module Index in general - it allows quick access Iain> to exactly what I want. I would like a minor change to it though Iain> - stop words starting with a given letter rolling over to another Iain> column (for example, os.path is at the foot of one column, while Iain> ossaudiodev is at the head of the next), and provide links to each Iain> initial letter at the top of the page.
I know it's not what you asked for, but give
http://staging.musi-cal.com/modindex/
a try. See if by dynamically migrating the most frequently requested modules to the front of the section it becomes more manageable.
I think this is pretty cool. But...
Is this only for the online docs? Would documentaion shipped with
Python exclude this, or have a frozen version of it?
My experience with other machine systems that try to guess what
I will want, is they usually get it wrong, and become more of a burdon
than a help.
Often what I like best is consistency. I think I'd find it irritating
if
I got used to clicking on one of the frequently used links, and then
discovered it had been bumped. Even it's changing position might
be irritating. http://staging.musi-cal.com/modindex/
rurpy> Is this only for the online docs?
Yes. I don't see that it would be helpful for static docs. Presumably they
will get reorganized. I want something for the many times I return to the
global module index looking for help with a particular module.
rurpy> My experience with other machine systems that try to guess what I
rurpy> will want, is they usually get it wrong, and become more of a
rurpy> burdon than a help.
This isn't guessing. It's more like voting (or like rating systems such as
the Internet Movie Database).
S
Aahz wrote: In article <x9********************@speakeasy.net>, A.M. Kuchling <am*@amk.ca> wrote:
So now we're *really* stuck. The RefGuide doesn't describe the rules; the PEP no longer describes them either; and probably only Guido can write the new text for the RefGuide. (Or are the semantics the same and only some trivial details are different?)
Raymond Hettinger (and/or maybe one of the metaclass wizards) can probably also write it, with Guido editing after. That might produce even more accuracy in the end.
I'm not a metaclass wizard, but I have submitted a few doc patches
trying to address some of the inaccuracies in the description of
new-style classes and related matters: http://www.python.org/sf/1123716 http://www.python.org/sf/1163367
The problem is that they don't seem to get accepted (even when
accompanied by positive comments). And unfortunately, I don't currently
have time to do the 5 reviews for 1 deal offered by some of the
python-dev folks.
STeVe
On 7 Dec 2005 05:51:45 -0800,
Iain King <ia******@gmail.com> wrote: Argh, you made me look at the html again - at least now I know *why* it is so disgusting. I understand there's a new version coming out soon, hopefully in html 4 strict or xhtml. I'm sure at that point it'll be easier to use. I can wait. :)
A new version of LaTeX2HTML, you mean? Can you provide a pointer?
--amk
On Wed, 07 Dec 2005 12:10:18 -0500,
Kent Johnson <ke**@kentsjohnson.com> wrote: OK I'll bite. That Beginners Guide page has bugged me for a long time. It's a wiki page but it is marked as immutable so I can't change it. Here are some immediate suggestions:
Good suggestions; thanks! I've applied most of them.
- Change the sentence "Read BeginnersGuide/Overview to learn the key points." to "Read BeginnersGuide/Overview to learn what makes Python special." Or maybe get rid of it completely - I'm not sure evangelism belongs on this page.
Yes, it does; fairly often the webmaster alias receives e-mails that
ask "so what is Python?"
--amk
Andrew,
The site changes for the new-to-Python person are a big improvement in
terms of the sequence of exposures, but from a marketing perspective,
the first thing they read about Python is still aimed at a programmer.
The bulleted points in BeginnersGuide/Overview are, again, things that
are important to programmers ("Automatic garbage collection frees you
from the hassles of memory management" means nothing to me, even now
after reading a Python book and several tutorials).
I wish there were some sort of sexy exposure to Python before hitting
them with the download. Again you purport to be making a page for
someone who's never programmed before, so almost certainly a Windows
user. And a Windows user is not going to download any program until
he's absolutely sure it won't destabilize his fragile system or infect
it. So nobody new to programming and new to Python is going to download
at the point you present them with that opportunity. Too bad there
isn't something like what Ruby does with the "Try Ruby In Your Browser"
thing, which is a very effective marketing tool (although obviously I
chose Python). http://tryruby.hobix.com/
The other thing I vividly recall struggling with was: Do I download
this Python.org version for my Windows XP machine, because it's the
official one, or do I use the one from ActiveState because others say
it comes with all sorts of goodies for Windows users? I don't know what
the politics are there, but if I were you I'd take a stand and put it
on the download page to help the new person out, who is uncertain about
what to do.
Ultimately I downloaded ActiveState because I found their site easier
to understand (again speaking as a person relatively new to programming
and absolutely new to Python).
Thanks,
rpd
"I read part of it all the way through."--Samuel Goldwyn www.dooling.com
A.M. Kuchling wrote: On Wed, 07 Dec 2005 12:10:18 -0500, Kent Johnson <ke**@kentsjohnson.com> wrote:
OK I'll bite. That Beginners Guide page has bugged me for a long time. It's a wiki page but it is marked as immutable so I can't change it. Here are some immediate suggestions:
Good suggestions; thanks! I've applied most of them.
Thanks, this is a big improvement. Here are a few more ideas:
- change "Next, you need to get the Python interpreter installed on your
computer." to "Next, install the Python interpreter on your computer."
(active voice)
- move and rewrite the "You'll want to select a [WWW] text editor..."
sentence. For a raw beginner, this is not the next step and the page it
links to will not be helpful. Tutorials generally start out at the
interpreter prompt, not writing programs in an editor. Whatever editor
is handy and familiar is probably fine for a first program when the time
comes. Here is a suggested rewrite:
"When you are ready to write your first program you will need a text
editor. To get started you can use any editor you are familiar with such
as NotePad or <insert names of other common editors>. As you gain
experience you may want to use a text editors with features that help
you write Python programs. A comprehensive list is here <link>."
I think I would put this before the paragraph beginning "Once you've
read a tutorial".
- Move the "Need to know how to run Python programs on Windows?"
sentence to the last bullet of the list in the next paragraph and
rewrite it to
"Most tutorials assume you know how to run a program on your computer.
If you are using Windows and need help with this, see <link>."
- Change "Next, you're going to want to read a tutorial" to "Next, read
a tutorial"
With these changes the first links on this page are BG/Overview,
BG/Download and BG/NonProgrammers. The second link on BG/NonProgrammers
is a reasonable tutorial and the first link is pretty obviously one to
skip. So a beginner is guided through the necessary steps with nothing
extra or distracting or overwhelming intervening. - Change the sentence "Read BeginnersGuide/Overview to learn the key points." to "Read BeginnersGuide/Overview to learn what makes Python special." Or maybe get rid of it completely - I'm not sure evangelism belongs on this page.
Yes, it does; fairly often the webmaster alias receives e-mails that ask "so what is Python?"
Direct them to the "What is Python?" link on the front page maybe? ISTM
the material in BG/Overview belongs on the pages linked from "What is
Python?"
Thanks,
Kent This thread has been closed and replies have been disabled. Please start a new discussion. Similar topics
by: Brian Quinlan |
last post by:
I was wondering if there is a system available that serves Python
documentation from a CGI script.
I want to use such a system internally at my company so we can browse
documentation for our...
|
by: Michael Klose |
last post by:
Hi,
not sure if this is the right group, if not, please post a followup to
the right group.
Basically, what I would like to do is to produce a documentation
cdrom, but which has a full text...
|
by: Terry Hancock |
last post by:
I've been trying to use "happydoc" to document a source
tree that I'm working on. It does pretty much what I want,
except:
Version 2.1:
Creates a weird directory structure for the HTML pages...
|
by: Colleyville Alan |
last post by:
I am looking for a shareware program to document an app and I really do not
like the built-in documentation in Access.
FMS Total Access Analyzer looks great, but it's way too pricey. I have seen...
|
by: Cameron Laird |
last post by:
QOTW: "Python makes it easy to implement algorithms." - casevh
"Most of the discussion of immutables here seems to be caused by
newcomers wanting to copy an idiom from another language which...
|
by: kpd |
last post by:
Hello,
I have written a C++ library that I've then wrapped with Pyrex.
Any suggestions to the best-in-class tool to create documentation for
the libraries?
I would love to document things in...
|
by: nicolasfr |
last post by:
Hi,
I am a bit disapointed with the current Python online documentation. I
have read many messages of people complaining about the documentation,
it's lack of examples and the use of complicated...
|
by: Coleen |
last post by:
Hi All :-)
I'm not sure where to post this, but my organization is looking for a good software application that is not terribly expensive that allows you to create documentationand help files and...
|
by: Mythran |
last post by:
Can someone please point me to some articles explaining how to convert the
code comment xml files into MSDN documentation? I've made some
modifications to Enterprise Library and would like to...
|
by: Faith0G |
last post by:
I am starting a new it consulting business and it's been a while since I setup a new website. Is wordpress still the best web based software for hosting a 5 page website? The webpages will be...
|
by: ryjfgjl |
last post by:
In our work, we often need to import Excel data into databases (such as MySQL, SQL Server, Oracle) for data analysis and processing. Usually, we use database tools like Navicat or the Excel import...
|
by: taylorcarr |
last post by:
A Canon printer is a smart device known for being advanced, efficient, and reliable. It is designed for home, office, and hybrid workspace use and can also be used for a variety of purposes. However,...
|
by: Charles Arthur |
last post by:
How do i turn on java script on a villaon, callus and itel keypad mobile phone
|
by: aa123db |
last post by:
Variable and constants
Use var or let for variables and const fror constants.
Var foo ='bar';
Let foo ='bar';const baz ='bar';
Functions
function $name$ ($parameters$) {
}
...
|
by: ryjfgjl |
last post by:
If we have dozens or hundreds of excel to import into the database, if we use the excel import function provided by database editors such as navicat, it will be extremely tedious and time-consuming...
|
by: emmanuelkatto |
last post by:
Hi All, I am Emmanuel katto from Uganda. I want to ask what challenges you've faced while migrating a website to cloud.
Please let me know.
Thanks!
Emmanuel
|
by: BarryA |
last post by:
What are the essential steps and strategies outlined in the Data Structures and Algorithms (DSA) roadmap for aspiring data scientists? How can individuals effectively utilize this roadmap to progress...
|
by: Hystou |
last post by:
There are some requirements for setting up RAID:
1. The motherboard and BIOS support RAID configuration.
2. The motherboard has 2 or more available SATA protocol SSD/HDD slots (including MSATA, M.2...
| |