Author ezio.melotti
Recipients dcbbcd, docs@python, eric.araujo, ezio.melotti, georg.brandl, terry.reedy
Date 2011-03-10.23:57:30
SpamBayes Score 2.95477e-08
Marked as misclassified No
Message-id <1299801454.48.0.691166208202.issue4966@psf.upfronthosting.co.za>
In-reply-to
Content
The advantage of having one big page is that you can ctrl+f easily without having to go back and forth from different pages
On the other hand, the page is not easy to browse (especially on small screens, mobile devices, old/slow pcs).

In this case I don't think that splitting the page is a problem, because the page contains information about different and fairly unrelated thing.

With pages like unittest or logging is not so easy to split because while working with them you might need to use several different functions/methods/classes and having their docs on two or more page will be annoying.  (FWIW I've been working a lot on the unittest doc to make it more "compact" and easier to browse, but there's still work to do.  We have also been considering to make a page for unittest "users" that explains how to write tests and use the assert methods and another for unittest "developers" that explains how to write test runners, suites and more advanced stuff.)

BTW .rst is really easy, and if you are not sure about something just try to build the doc with "make html" and see if it complains and if the resulting page looks OK.  Also see http://docs.python.org/documenting/index.html.
History
Date User Action Args
2011-03-10 23:57:34ezio.melottisetrecipients: + ezio.melotti, georg.brandl, terry.reedy, dcbbcd, eric.araujo, docs@python
2011-03-10 23:57:34ezio.melottisetmessageid: <1299801454.48.0.691166208202.issue4966@psf.upfronthosting.co.za>
2011-03-10 23:57:30ezio.melottilinkissue4966 messages
2011-03-10 23:57:30ezio.melotticreate