The best doc help right now would probably be documenting web2py in a way which Sphinx could be used to generate the online documentation. Isnt this how python does it?
I have started by documenting anything new I might contribute. -Thadeus On Thu, Feb 4, 2010 at 4:12 PM, mdipierro <[email protected]> wrote: > Let me clarify. I am in the business of writing the book. That is my > job. I am in academia. That is how I justify my time on web2py. > > You are in the business of writing online docs. These are separate > projects. > > On Feb 4, 10:39 am, villas <[email protected]> wrote: >> On Feb 3, 8:58 pm, mdipierro <[email protected]> wrote: >> >> > Denes is right. >> >> Hi Massimo, >> Well, more specifically then: >> >> 1. Do you agree that it's a good idea to use the current book to make >> an online book? If not, let's forget it. > > No. There is more marketing value in claiming there is a published > book then online documentation (the latter is no guarantee of quality > for potential corporate users of web2py). Anyway it is not an option > because I have agreements with the publisher. You can use examples, > code and screen-shots from the book not text, unless translated in a > different language. > >> 2. Do you have an opinion on what form the online book should take? >> e.g. Djanjo, Cakephp, Php.net manual with comments... > > No. I work on the published book. You decide the rest. > >> 3. Income. Will the online book project negatively affects the income >> from the book. To make sure that this does not lead to a problem, I >> propose that you make a suggestion as to how this may be compensated. >> I suggest alternatives might include adsense, a subscription model, >> and donations, etc for access to all the update notes. Of course, >> even If the online book became the main place for the documentation to >> be updated, you could still sell the paper version. This would be >> something for you to decide / accept. > > This is not a problem. The income from the book is negligible and not > the reason for having the book (the image is more important that the > revenues). You should not worry about this. If the online docs get > better than the book and nobody buys the book it is my problem, not > yours, nor web2py's. > >> 4. What format should we use for the text? (Markdown, please?) > > This was discussed at length before and most people said reST so we > integrated reST in wiki (which was originally markdown). This is not a > technology issue (it is easy to do conversions). The issue is writing > the text. > >> 5 .It is important for the domain to belong to Web2py/Massimo. May I >> suggest book.web2py.com? > > I am happy to link a new page when it contains usable information, > else it looks bad. We have done it already with the wiki, we have done > it with web2pyslices. The think is I have seen this kind of project > start many times before and never move much forward (except wiki and > web2pyslices). I think it would be safer to extend what we have and > then build another domain if necessary. Anyway, as a rule I am happy > to link any initiative originating by users if it contains useful > info. > >> 6. No one will take the online book project seriously unless we also >> think about the roles we would need to fill. There are people in this >> community with much greater project expertise than I, so please feel >> free to dismiss the following. I am only making suggestions. e.g. >> - Model Designer. It is crucial that the data is saved in the most >> logical way for the future. This shouldn't be trusted to someone like >> me! I vote for you (Massimo), if you have time. Part of my >> reasoning is that you know how to design a workable versioning >> system :-) >> - Project Manager. Allocate tasks (and fire people!), supervise, >> coordinate timeline. >> - Programmers for controllers and views. Maybe split this into two: >> Admin and Enduser. >> - Html, CSS and JQuery effects (optional extra, can come later) >> - Data Loaders to copy and paste the sections of the book. I think >> I'd be good at this one, if the project manager would have me! >> >> Sorry to ask/make these specific questions/suggestions, but without >> your support (Massimo), let's be realistic, a community effort to >> produce and support the online book project probably isn't going to >> happen. > > Honestly I have seen this effort start many times. People are really > motivated but it takes more effort than you think. I know it because I > did with the book. It was hard and took months of full time work even > if I knew well what I was talking about. > > I strongly suggest that you start by improving the docstring by making > rest compliant and then you generate the online docs from them. You > will only need to add some overview pages and faq. > > Massimo > > -- > You received this message because you are subscribed to the Google Groups > "web2py-users" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/web2py?hl=en. > > -- You received this message because you are subscribed to the Google Groups "web2py-users" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
