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 page http://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 api http://docs.djangoproject.com/en/1.1/ref/ is really different from this http://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.
