state of documentation: why pdf?
pistacchio
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.
Richard
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.
> 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
pistacchio
On Jan 28, 12:48 pm, Richard <richar...@gmail.com> wrote:
> 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.
if this is the reason (and it is indeed a valid one), than nobody
would keep us from having both a pdf and a html version. to start off,
the internet version could a reorganization / htmlized version of the
pdf, than we can expand it with examples, cross references, and keep
it up to date with the changes made in various revisions. the
university pdf, on the other hand, could expand and be kept updated
with the material from the html version. my 2 cents.
mdipierro
forms of documentations (html, etc).
Nobody prevents you to write any documentation you like.
My job is write the book and I will concentrate on it. That is how can
justify the time I spend on web2py.
Massimo
Mengu
so, are we able to write a documentation on web2py?
Albert Abril
Any new documentation is welcome.
--
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+un...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
mdipierro
paste text from the book.
I can tell you right now that you are free to use all the code example
from the book as well as pictures but not the English text to avoid
copyright problems with the publisher. Exceptions can be made for
specific parts.
Massimo