Yes, I see it, thanks. I really do not like this format for a reference manual. Just a personal preference. Sorry.
I do like the PHP index and cross linking, and I do think there are some good ideas there, but I think a Reference Manual should be less of a forum and more documentation oriented. In particular, I'm looking to get away from a linear narrative and go to a very high-density highly-cross-linked source of information. On Jul 12, 2:45 am, Bruno Rocha <[email protected]> wrote: > Look what i am talking about, in action > ->http://www.pyforum.org/pyforum/default/view_topic/507 > > 2010/7/12 Bruno Rocha <[email protected]> > > > > > > > PHP manual is great, I always use, the information are easy to find, and > > connections with related subjects are simple, one advantage is that it was > > written in a way that allows various applications, badges, widgets etc using > > your content > > > I think that information in the PHP manual is organized much like a forum, > > the first post is a detailed explanation, with some examples. < > >http://www.php.net/manual/en/language.operators.php> The replies below > > are more examples of different scenarios for the same explained function. > > > With a good moderation, preventing unnecessary comments for each thread, > > PyForumhttp://www.pyforum.org/could be a great start, may be, changing > > PyForum to accept Markmin, and a good way for publish live demo examples. > > > Simply gather a team, and start writing, in this way each person moderates > > others. > > > 2010/7/12 mdipierro <[email protected]> > > > This issue issue comes up regularly and my answer does not change. > > >> I very much welcome a community effort to have a better documentation. > >> It was attempted many times before and many times it has failed. It > >> failed because people think it is a technological issue (which wiki do > >> we use?) but it is not. The problem is keeping the docs in sync with > >> code is a pedantic issue and there is not enough motivation. > > >> The problem with the book is that content is copyrighted and I have an > >> agreement with the publisher. I have already lost $600/month in > >> revenues from book sales since the book was posted online. This has > >> not been bade up by donations. > > >> I am in the process of revising the online book online: > >> - add new sections > >> - move from markdown to markmin > >> - include an automatic markmin to pdf (for download) > >> - make it more friendly to users > > >> As far as I am concerned I need help with docstings, examples in > >> docstrigns, and more tests. > > >> I will look into the php wiki you refer to. > > >> Massimo > > >> > Massimo, do you think 5M pageviews would be exceeded in any month for > >> > the time being? > > >> > ra3don: I like your idea of a download version. If we pack all into > >> > a .w2p then the downloadable reference manual would be implemented. > >> > Then you could install it on your local machine and access it later, > >> > even if you didn't have an internet connection. Great for coding while > >> > traveling! > > >> > Massimo, is the cube2py wiki ready to take on this task on GAE? If > >> > yes, I say we get on with it. We'd need volunteers to setup and > >> > administer. > > >> > Once set up, the first order of business would be to develop (wiki > >> > pages, of course) a style guide for the various types of pages in the > >> > Reference Manual. The pages I can think of three types of pages off > >> > the top of my head: > > >> > Index pages > >> > - organized alphabetically by function > >> > - organized alphabetically by parameter/attribute (non-statement) > >> > Manual page for web2py function > >> > Manual page for web2py parameter/attributes > > > -- > > >http://rochacbruno.com.br > > -- > > http://rochacbruno.com.br- Hide quoted text - > > - Show quoted text -
