On Mon, Apr 11, 2011 at 2:35 PM, Francesc Alted <[email protected]> wrote: > 2011/4/11 William Stein <[email protected]> >> >> 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.
Thanks for the suggestions. Done. > 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! +1, and thanks, Fransesc, for the work you've started in moving us in this direction. - Robert _______________________________________________ cython-devel mailing list [email protected] http://mail.python.org/mailman/listinfo/cython-devel
