On Jul 12, 2010, at 9:20 AM, weheh wrote: > 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.
Right. No reason it can't link *out* to tutorials and such, but it should be a complete reference in itself. (In the case of web2py, linking out is important, since there are so many disparate sources of information floating around.) This discussion has a tendency to degenerate into a back & forth about choosing tools (or hosts). Massimo's new wiki seems like a natural choice at this point; I have no idea about hosting, though I suppose that GAE would make an interesting demo (a secondary consideration, of course). > > > 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 -
