Discussion:
can I help with the docs?
(too old to reply)
Andrew Hawryluk
2009-08-11 19:10:39 UTC
Permalink
I'd like to help with the docs project. I have registered a user name of
ahawryluk on the Wiki.
Although the current focus is cleaning up the docstrings on the numpy
module, I'm most interested in writing some introductory material for
the NumPy User Guide.

Andrew Hawryluk
NOVA Chemicals Research & Technology Centre
Calgary, Canada
David Goldsmith
2009-08-11 19:15:39 UTC
Permalink
Hi, Andrew, and thanks for your offer to help. Can you be more specific vis-a-vis what you have in mind?

David Goldsmith, Technical Editor
Olympia, WA
Subject: [SciPy-dev] can I help with the docs?
Date: Tuesday, August 11, 2009, 12:10 PM
I'd like to help with the docs
project. I have registered a user name of
ahawryluk on the Wiki.
Although the current focus is cleaning up the docstrings on
the numpy
module, I'm most interested in writing some introductory
material for
the NumPy User Guide.
Andrew Hawryluk
NOVA Chemicals Research & Technology Centre
Calgary, Canada
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
Andrew Hawryluk
2009-08-11 20:08:30 UTC
Permalink
Good question. I'll let you know what I was thinking, and then you can
tell me if I've misunderstood the documentation objectives.

Each year I train a new set of engineering internship students in our
department, and one of the things they learn is Python. Upon arriving
here they have taken a single course on C++ and another on
Matlab/Mathematica/Excel etc., but no Python. I usually start them off
reading "Dive Into Python", but I'd also like a single place to send
them to get a brief tour of proper NumPy use. The main NumPy & SciPy
docs are excellent (and improving rapidly), but they start a bit too
abruptly for my needs. For example, the NumPy User Guide currently start
with installation instructions, and then the next page of body text is a
table of all the available array types.

I would like something that briefly explains what NumPy and SciPy are,
and why/when arrays are better than lists/dicts, perhaps followed by a
brief tour of some common NumPy tricks, before diving into the more
detailed sections.

One possible table of contents would be

Introduction
What is NumPy?
Building/Installing
Short Tour
How to find documentation
NumPy Basics
...

What direction were you thinking the User Guide would take?

Andrew
-----Original Message-----
On Behalf Of David Goldsmith
Sent: 11 Aug 2009 1:16 PM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the docs?
Hi, Andrew, and thanks for your offer to help. Can you be more
specific vis-a-vis what you have in mind?
David Goldsmith, Technical Editor
Olympia, WA
Subject: [SciPy-dev] can I help with the docs?
Date: Tuesday, August 11, 2009, 12:10 PM I'd like to help with the
docs project. I have registered a user name of ahawryluk on the
Wiki.
Although the current focus is cleaning up the docstrings on the
numpy
module, I'm most interested in writing some introductory material
for
the NumPy User Guide.
Andrew Hawryluk
NOVA Chemicals Research & Technology Centre Calgary, Canada
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
nicky van foreest
2009-08-11 21:06:52 UTC
Permalink
Hi Andrew,

I do not want to interfere with the scipy doc project... However,
after having read your ideas, might this cover your needs, at least in
part?

http://johnstachurski.net/lectures/index.html

bye

Nicky
Post by Andrew Hawryluk
Good question. I'll let you know what I was thinking, and then you can
tell me if I've misunderstood the documentation objectives.
Each year I train a new set of engineering internship students in our
department, and one of the things they learn is Python.  Upon arriving
here they have taken a single course on C++ and another on
Matlab/Mathematica/Excel etc., but no Python.  I usually start them off
reading "Dive Into Python", but I'd also like a single place to send
them to get a brief tour of proper NumPy use.  The main NumPy & SciPy
docs are excellent (and improving rapidly), but they start a bit too
abruptly for my needs. For example, the NumPy User Guide currently start
with installation instructions, and then the next page of body text is a
table of all the available array types.
I would like something that briefly explains what NumPy and SciPy are,
and why/when arrays are better than lists/dicts, perhaps followed by a
brief tour of some common NumPy tricks, before diving into the more
detailed sections.
One possible table of contents would be
Introduction
 What is NumPy?
 Building/Installing
 Short Tour
 How to find documentation
NumPy Basics
 ...
What direction were you thinking the User Guide would take?
Andrew
-----Original Message-----
On Behalf Of David Goldsmith
Sent: 11 Aug 2009 1:16 PM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the docs?
Hi, Andrew, and thanks for your offer to help.  Can you be more
specific vis-a-vis what you have in mind?
David Goldsmith, Technical Editor
Olympia, WA
Subject: [SciPy-dev] can I help with the docs?
Date: Tuesday, August 11, 2009, 12:10 PM I'd like to help with the
docs project. I have registered a user name of ahawryluk on the
Wiki.
Although the current focus is cleaning up the docstrings on the
numpy
module, I'm most interested in writing some introductory material
for
the NumPy User Guide.
Andrew Hawryluk
NOVA Chemicals Research & Technology Centre Calgary, Canada
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
Andrew Hawryluk
2009-08-11 23:15:48 UTC
Permalink
Thanks for the link! I will certainly include that in my list of helpful training materials.

Andrew
-----Original Message-----
On Behalf Of nicky van foreest
Sent: 11 Aug 2009 3:07 PM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the docs?
Hi Andrew,
I do not want to interfere with the scipy doc project... However, after
having read your ideas, might this cover your needs, at least in part?
http://johnstachurski.net/lectures/index.html
bye
Nicky
Post by Andrew Hawryluk
Good question. I'll let you know what I was thinking, and then you
can
Post by Andrew Hawryluk
tell me if I've misunderstood the documentation objectives.
Each year I train a new set of engineering internship students in our
department, and one of the things they learn is Python.  Upon
arriving
Post by Andrew Hawryluk
here they have taken a single course on C++ and another on
Matlab/Mathematica/Excel etc., but no Python.  I usually start them
off reading "Dive Into Python", but I'd also like a single place to
send them to get a brief tour of proper NumPy use.  The main NumPy &
SciPy docs are excellent (and improving rapidly), but they start a
bit
Post by Andrew Hawryluk
too abruptly for my needs. For example, the NumPy User Guide
currently
Post by Andrew Hawryluk
start with installation instructions, and then the next page of body
text is a table of all the available array types.
I would like something that briefly explains what NumPy and SciPy
are,
Post by Andrew Hawryluk
and why/when arrays are better than lists/dicts, perhaps followed by
a
Post by Andrew Hawryluk
brief tour of some common NumPy tricks, before diving into the more
detailed sections.
One possible table of contents would be
Introduction
 What is NumPy?
 Building/Installing
 Short Tour
 How to find documentation
NumPy Basics
 ...
What direction were you thinking the User Guide would take?
Andrew
-----Original Message-----
On Behalf Of David Goldsmith
Sent: 11 Aug 2009 1:16 PM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the docs?
Hi, Andrew, and thanks for your offer to help.  Can you be more
specific vis-a-vis what you have in mind?
David Goldsmith, Technical Editor
Olympia, WA
Subject: [SciPy-dev] can I help with the docs?
Date: Tuesday, August 11, 2009, 12:10 PM I'd like to help with the
docs project. I have registered a user name of ahawryluk on the
Wiki.
Although the current focus is cleaning up the docstrings on the
numpy
module, I'm most interested in writing some introductory material
for
the NumPy User Guide.
Andrew Hawryluk
NOVA Chemicals Research & Technology Centre Calgary, Canada
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
Gael Varoquaux
2009-08-13 09:58:22 UTC
Permalink
Post by Andrew Hawryluk
Each year I train a new set of engineering internship students in our
department, and one of the things they learn is Python. Upon arriving
here they have taken a single course on C++ and another on
Matlab/Mathematica/Excel etc., but no Python. I usually start them off
reading "Dive Into Python", but I'd also like a single place to send
them to get a brief tour of proper NumPy use. The main NumPy & SciPy
docs are excellent (and improving rapidly), but they start a bit too
abruptly for my needs. For example, the NumPy User Guide currently start
with installation instructions, and then the next page of body text is a
table of all the available array types.
I would like something that briefly explains what NumPy and SciPy are,
and why/when arrays are better than lists/dicts, perhaps followed by a
brief tour of some common NumPy tricks, before diving into the more
detailed sections.
One possible table of contents would be
Introduction
What is NumPy?
Building/Installing
Short Tour
How to find documentation
NumPy Basics
...
What direction were you thinking the User Guide would take?
Hey Andrew,

Good documentation, including documentation targetting newcomers, as you
point out, is paramount. I have also found that it is a tremendous amount
of work, because it requires reworking and revisiting the complete set of
available documentation all the time, to make sure that you have a
consistent set, that fits together in a narrative way, but also that
drive the reader to where he wants quickly.

I would very much like the numpy user guide, that you can edit on the
docwiki, to be that documentation. The reason being that it is a shared
project (it is easy for people to edit it), and thus it is easier to work
together and gather momentuml, that it is the 'official' documentation,
and thus will get more exposure, and that it is stored internally in a
format (sphinx) that makes it possible to produce an online doc as well
as a printed doc.

So I would say: just go ahead, and make your proposed changes in the
docwiki. They seem very sensible. If you have any problems, or want
review, ask on the mailing list. I say ask, I could say 'yell'. People
are all struggling with day-to-day life, deadlines, and many projects, so
you will probably not get as much review as you would like. However, in
my experience, such contributions grow the available material and end up
making it better all the time.

One thing that we have to be careful about, is not to repeat ourselves
too much in the documentation. If we do, the documentation can become a
huge maze that noones read. I believe the answer to this problem is to
cross link a lot, and to try to improve existing articles, when
available.

Thanks a lot for your interest,

Gaël
David Goldsmith
2009-08-11 22:17:09 UTC
Permalink
Post by Andrew Hawryluk
I would like something that briefly explains what NumPy and
SciPy are,
and why/when arrays are better than lists/dicts, perhaps
followed by a
brief tour of some common NumPy tricks, before diving into
the more
detailed sections.
One possible table of contents would be
Introduction
  What is NumPy?
  Building/Installing
  Short Tour
  How to find documentation
NumPy Basics
  ...
What direction were you thinking the User Guide would
take?
Good question, especially as I don't think there's as clear a vision on that (certainly not as a matter of consensus) as yours is for what you want/need. Personally, my "advice" to you would be: draft the document/sections you would like to see added - then you'll have what you want regardless of how/when it gets added to the "official" User Guide - and then post it (or a link to it) here to be vetted, if you want. That said,

http://docs.scipy.org/numpy/docs/numpy-docs/user/index.rst/

is the link to the Wiki (pydocweb) interface for editing the official User Guide, and you're more than welcome to add your content that way; of course, for better or worse, that's a Wiki, so whatever you add there will be subject to review and edit (but that's going to be true for any contribution to the official doc, of course). Note that there you'll find a link to a section titled "NumPy Basics" w/ further links to sub-sections "types," "array creation," "indexing," and so forth - if that content is *not* what you've already read (there's a lot of doc in the Wiki - anything that's not past the proof stage, basically - that's pending inclusion in anything official) be sure to look it over, as it may already contain some (much?) of what you're after. Thanks again,

DG

PS: If your original email was (primarily) intended to have someone grant you edit permissions, I'm afraid I haven't been granted that power yet, so you'll have to wait until someone who does, does.
Post by Andrew Hawryluk
Andrew
-----Original Message-----
On Behalf Of David Goldsmith
Sent: 11 Aug 2009 1:16 PM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the docs?
Hi, Andrew, and thanks for your offer to help. 
Can you be more
specific vis-a-vis what you have in mind?
David Goldsmith, Technical Editor
Olympia, WA
Subject: [SciPy-dev] can I help with the docs?
Date: Tuesday, August 11, 2009, 12:10 PM I'd like
to help with the
docs project. I have registered a user name of
ahawryluk on the
Wiki.
Although the current focus is cleaning up the
docstrings on the
numpy
module, I'm most interested in writing some
introductory material
for
the NumPy User Guide.
Andrew Hawryluk
NOVA Chemicals Research & Technology Centre
Calgary, Canada
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
Andrew Hawryluk
2009-08-11 23:13:49 UTC
Permalink
That sounds good. I will draft up some ideas, and submit them for comment / review / merciless editing.
Yes, the 'NumPy Basics' section covers most of the important ground, so I will re-read it before I suggest anything.

Thanks,
Andrew
-----Original Message-----
On Behalf Of David Goldsmith
Sent: 11 Aug 2009 4:17 PM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the docs?
Post by Andrew Hawryluk
I would like something that briefly explains what NumPy and SciPy
are,
Post by Andrew Hawryluk
and why/when arrays are better than lists/dicts, perhaps followed by
a
Post by Andrew Hawryluk
brief tour of some common NumPy tricks, before diving into the more
detailed sections.
One possible table of contents would be
Introduction
  What is NumPy?
  Building/Installing
  Short Tour
  How to find documentation
NumPy Basics
  ...
What direction were you thinking the User Guide would take?
Good question, especially as I don't think there's as clear a vision on
that (certainly not as a matter of consensus) as yours is for what you
want/need. Personally, my "advice" to you would be: draft the
document/sections you would like to see added - then you'll have what
you want regardless of how/when it gets added to the "official" User
Guide - and then post it (or a link to it) here to be vetted, if you
want. That said,
http://docs.scipy.org/numpy/docs/numpy-docs/user/index.rst/
is the link to the Wiki (pydocweb) interface for editing the official
User Guide, and you're more than welcome to add your content that way;
of course, for better or worse, that's a Wiki, so whatever you add
there will be subject to review and edit (but that's going to be true
for any contribution to the official doc, of course). Note that there
you'll find a link to a section titled "NumPy Basics" w/ further links
to sub-sections "types," "array creation," "indexing," and so forth -
if that content is *not* what you've already read (there's a lot of doc
in the Wiki - anything that's not past the proof stage, basically -
that's pending inclusion in anything official) be sure to look it over,
as it may already contain some (much?) of what you're after. Thanks
again,
DG
PS: If your original email was (primarily) intended to have someone
grant you edit permissions, I'm afraid I haven't been granted that
power yet, so you'll have to wait until someone who does, does.
Post by Andrew Hawryluk
Andrew
-----Original Message-----
On Behalf Of David Goldsmith
Sent: 11 Aug 2009 1:16 PM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the docs?
Hi, Andrew, and thanks for your offer to help.
Can you be more
specific vis-a-vis what you have in mind?
David Goldsmith, Technical Editor
Olympia, WA
Subject: [SciPy-dev] can I help with the docs?
Date: Tuesday, August 11, 2009, 12:10 PM I'd like
to help with the
docs project. I have registered a user name of
ahawryluk on the
Wiki.
Although the current focus is cleaning up the
docstrings on the
numpy
module, I'm most interested in writing some
introductory material
for
the NumPy User Guide.
Andrew Hawryluk
NOVA Chemicals Research & Technology Centre
Calgary, Canada
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
David Goldsmith
2009-08-11 23:32:20 UTC
Permalink
You're very welcome! Thank you for helping!

DG
Subject: Re: [SciPy-dev] can I help with the docs?
Date: Tuesday, August 11, 2009, 4:13 PM
That sounds good. I will draft up
some ideas, and submit them for comment / review / merciless
editing.
Yes, the 'NumPy Basics' section covers most of the
important ground, so I will re-read it before I suggest
anything.
Thanks,
Andrew
-----Original Message-----
On Behalf Of David Goldsmith
Sent: 11 Aug 2009 4:17 PM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the docs?
Post by Andrew Hawryluk
I would like something that briefly explains what
NumPy and SciPy
are,
Post by Andrew Hawryluk
and why/when arrays are better than lists/dicts,
perhaps followed by
a
Post by Andrew Hawryluk
brief tour of some common NumPy tricks, before
diving into the more
Post by Andrew Hawryluk
detailed sections.
One possible table of contents would be
Introduction
  What is NumPy?
  Building/Installing
  Short Tour
  How to find documentation
NumPy Basics
  ...
What direction were you thinking the User Guide
would take?
Good question, especially as I don't think there's as
clear a vision on
that (certainly not as a matter of consensus) as yours
is for what you
want/need.  Personally, my "advice" to you would
be: draft the
document/sections you would like to see added - then
you'll have what
you want regardless of how/when it gets added to the
"official" User
Guide - and then post it (or a link to it) here to be
vetted, if you
want.  That said,
http://docs.scipy.org/numpy/docs/numpy-docs/user/index.rst/
is the link to the Wiki (pydocweb) interface for
editing the official
User Guide, and you're more than welcome to add your
content that way;
of course, for better or worse, that's a Wiki, so
whatever you add
there will be subject to review and edit (but that's
going to be true
for any contribution to the official doc, of
course).  Note that there
you'll find a link to a section titled "NumPy Basics"
w/ further links
to sub-sections "types," "array creation," "indexing,"
and so forth -
if that content is *not* what you've already read
(there's a lot of doc
in the Wiki - anything that's not past the proof
stage, basically -
that's pending inclusion in anything official) be sure
to look it over,
as it may already contain some (much?) of what you're
after.  Thanks
again,
DG
PS: If your original email was (primarily) intended to
have someone
grant you edit permissions, I'm afraid I haven't been
granted that
power yet, so you'll have to wait until someone who
does, does.
Post by Andrew Hawryluk
Andrew
-----Original Message-----
On Behalf Of David Goldsmith
Sent: 11 Aug 2009 1:16 PM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the
docs?
Post by Andrew Hawryluk
Hi, Andrew, and thanks for your offer to
help.
Post by Andrew Hawryluk
Can you be more
specific vis-a-vis what you have in mind?
David Goldsmith, Technical Editor
Olympia, WA
Subject: [SciPy-dev] can I help with
the docs?
Post by Andrew Hawryluk
Date: Tuesday, August 11, 2009, 12:10
PM I'd like
Post by Andrew Hawryluk
to help with the
docs project. I have registered a user
name of
Post by Andrew Hawryluk
ahawryluk on the
Wiki.
Although the current focus is cleaning
up the
Post by Andrew Hawryluk
docstrings on the
numpy
module, I'm most interested in writing
some
Post by Andrew Hawryluk
introductory material
for
the NumPy User Guide.
Andrew Hawryluk
NOVA Chemicals Research &
Technology Centre
Post by Andrew Hawryluk
Calgary, Canada
_______________________________________________
Post by Andrew Hawryluk
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Post by Andrew Hawryluk
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________
Scipy-dev mailing list
http://mail.scipy.org/mailman/listinfo/scipy-dev
Gael Varoquaux
2009-08-13 17:52:42 UTC
Permalink
Post by Andrew Hawryluk
I'd like to help with the docs project. I have registered a user name of
ahawryluk on the Wiki.
Although the current focus is cleaning up the docstrings on the numpy
module, I'm most interested in writing some introductory material for
the NumPy User Guide.
Hey Andrew,

I have added you to the editor list, you can now edit docs on the
docwiki. Sorry for the slow reply, I have been on holidays lately.

Gaël
Andrew Hawryluk
2009-08-13 20:34:40 UTC
Permalink
-----Original Message-----
On Behalf Of Gael Varoquaux
Sent: 13 Aug 2009 11:53 AM
To: SciPy Developers List
Subject: Re: [SciPy-dev] can I help with the docs?
Hey Andrew,
I have added you to the editor list, you can now edit docs on the
docwiki. Sorry for the slow reply, I have been on holidays lately.
Gaël
No problem, and welcome back. Thanks for the encouragement on the docs!

Andrew

Continue reading on narkive:
Loading...