2011/4/11 William Stein <wst...@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
_______________________________________________ cython-devel mailing list cython-devel@python.org http://mail.python.org/mailman/listinfo/cython-devel
