I totally agree - the manual is a great resource but the PDF format makes it hard to traverse and doesn't keep up with new features. Django docs are excellent.
This was brought up previously and the main obstacle (IIRC) is Massimo needs publications to justify working on web2py for his university. Hopefully a compromise can be reached. On Jan 28, 9:00 pm, pistacchio <pistacc...@gmail.com> wrote: > hi to all, > after a long session of web2py coding, i feel now a bit frustrated by > the documentation. i don't think that .pdf is the best format for > documenting an opensource project. > > every time you need to look up something you have to search the whole > document for a keyword and read through the found pages or go back to > the beginning of the document for the summary, scroll looking for what > you're after (or do the same with the glossary on the last pages). > then scroll to the page number or input it to go there. of course the > _pdf_ page number doesn't match with the _document_ number, so there's > some additional scrolling for some 5 - 10 pages. > using a pdf as reference is really buggy. when i have a doubt like > "what's that parameter?" or "how's that example?" i don't really feel > scrolling between pages, i want to click links and get answers. > > now, i find the scribd thing really annoying, so i bought the pdf from > lulu. i mostly did it to fund the project, indeed. it is, of course, > not updated. for example i imported some modules with "import > applications.myapp.modules.mymodule as mymodule", as the manual said. > i changed the project name and it broke. a search in the newsgroup > pointed me to local_import. local_import is nowhere referred to in the > pdf. > other example. i'm now aware of the urlify method found in the latest > revision because i'm now actively following the newsgroup and mostly > because i contributed it, but i wonder how many useful modules and > amazing functions are there that i'm not aware of because of this lack > in the documentation. i think it is scattered and not well organized. > > i moved away from django and i'm really happy of having found web2py > but honestly this pagehttp://docs.djangoproject.com/en/1.1/contents/ > (django documentation) is something to copy from, all indexed, > organized, always up-to-date and full of examples. there are multiple > entry points, from the "getting started" tutorial if you're now, to > the "using django" that is more complete and in-depth to the api for a > quick reference. mind you, this apihttp://docs.djangoproject.com/en/1.1/ref/ > is really different from > thishttp://www.web2py.com/examples/static/epydoc/index.html > because, being human-written, is full of examples, caveats, > suggestions and multiple references to other sections of the > documentation where the subject is explained. > > the choice of the pdf format seems really money-driven and, sorry to > say, this works really bad with an open source project. if really > money is the key problem here (eg: selling the pdf is used to pay the > hosting), i'd be happy to fund the initial shift of the documentation > to a more maintainable format. -- You received this message because you are subscribed to the Google Groups "web2py-users" group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
