[Cython] "Cython's Users Guide"

[Francesc Alted]

2011/4/11 William Stein <wstein at gmail.com>

> Hi,
>
> I'm teaching Cython in my Sage course yet again, and noticed that
> again there are some very confusing aspects of the Cython
> documentation organization, which could probably be improved by a few
> simple changes.
>
>  1. At http://cython.org/ there is a big link in the middle of the
> page labeled "Cython Users Guide" which goes to
> http://docs.cython.org/.   However, http://docs.cython.org/ is *not*
> the users guide -- it is "Cython’s Documentation".     In fact, the
> Users Guide is Chapter 3 of the documentation.
>
>  2. Looking at http://docs.cython.org, we see that Chapter 2 is
> "Tutorials".  But then looking down to Chapter 3 we see that it is
> "Cython Users Guide".  Of course, that's what one is after having just
> clicked a link called "Cython Users Guide".  So we click on "Cython
> Users Guide" again.
>
>  3. We arrive at a page that again has "Tutorial" as Chapter 2.   For
> some reason this makes me feel even more confused.
>
> Recommend changes:
>
>  1. Change the link on the main page from "Cython Users Guide" to
> "Documentation"  or put a direct link into the Users Guide, or have
> two links.
>
>  2. At http://docs.cython.org/ rename the "Cython Users Guide" to
> "Users Guide", since it is obviously the Cython Users Guide at this
> point and "Cython documentation" is in the upper left of the page
> everywhere.
>
>  3. Possibly rename the tutorial in chapter 2 of the users guide to
> something like "First Steps" or "Basic Tutorial" or something.
>

Yeah, that's something that we discussed in the past workshop in Munich
(BTW, many thanks for providing the means for making this happen!).  The
basic idea is to completely remove the Chapter 3 (Cython Users Guide) by
moving its parts to either Chapter 2 (Tutorials), or either to Chapter 4
(Reference Guide).  During the meeting we agreed that the doc repository
should be moved (and has been moved indeed) into the source repo, so that
modifications that affect to code and docs can be put in the same
commit/branch. Also, the wiki has a lot of information that can be better
consolidated and integrated into the User's Guide.

In fact, I already started some job in this direction and created a couple
of pull requests during the workshop (that they have been already
integrated).  I plan to continue this job, but unfortunately I'm pretty busy
lately, so I don't think I can progress a lot in the next weeks, so if
anybody is interested in joining the effort for improving Cython's
documentation, she will be very welcome indeed!

-- 
Francesc Alted
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/cython-devel/attachments/20110411/a13bbb7c/attachment.html>