Re: Vedr. [Zope3-Users] Zope 3 API documentation needs a new strategy
Luciano Ramalho wrote: And finally, the wiki Documentation page does not mention the abundant README.txt files scattered all over the source tree where the real documentation exists. Yup, I agree that the README.txt's have a lot of useful info but how would you know to look for them if you were new to Z3 ? I also agree with the comment about PHP documentation - I can't stand PHP, but you can't argue with the size of the community that they must be doing something right, perhaps meeting the needs of the target audience ? :-) I think Z3 is awesome, but is (IMHO) still not really ready for a larger audience than the devotees using it now, mostly because of little things like documentation. Cheers, Andrew. ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
Re: Vedr. [Zope3-Users] Zope 3 API documentation needs a new strategy
On 7/18/07, Benji York <[EMAIL PROTECTED]> wrote: Does http://wiki.zope.org/zope3/Documentation help? Not really. Before yesterday, there was no explanation about how to access apidoc (I put that in the linked page APIDocTool yesterday). The apidoc tool itself is limited. For debugging purposes, it might be useful that the search is limited to registered interfaces. But while reading about Zope 3 I wanted to check on IComponentArchitecture but the search could not find it. I had to use grep to find it and learn the path that I could use to browse to it in the apidoc: http://localhost:8099/++apidoc++/Interface/zope.component.interfaces.IComponentArchitecture/index.html And finally, the wiki Documentation page does not mention the abundant README.txt files scattered all over the source tree where the real documentation exists. Cheers, Luciano PS. BTW, I'd like to mention that besides the people who replied in the list, I got pvt replies of people saying that they feel the same way as I do about the current docs. ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
Re: Vedr. [Zope3-Users] Zope 3 API documentation needs a new strategy
Torvald Bringsvor wrote: Very good point I think. The current documentation makes me feel stupid, sometimes wanting to go in some other direction than Z3. Does http://wiki.zope.org/zope3/Documentation help? -- Benji York Senior Software Engineer Zope Corporation ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
Vedr. [Zope3-Users] Zope 3 API documentation needs a new strategy
Very good point I think. The current documentation makes me feel stupid, sometimes wanting to go in some other direction than Z3. -Torvald --- Luciano Ramalho <[EMAIL PROTECTED]> skrev: > One of the first questions anyone needs answered > when studying a new > framework is "Where is the canonical reference for > the API?". > > If you google for "zope 3 api documentation" the > first link is Stephan > Richter's mail of Jan/2004 announcing API doc. In > it, there is the > link: > > http://localhost:8080/++apidoc++ > > However, that URL is not active by default, and it > takes some research > discover how to make it work. > > The second link returned by Google is this: > > http://wiki.zope.org/zope3/Documentation > > Here we find vague references to a certain API Doc > Tool, but no > explanation of how to enable it and access it (OK, > that is a Wiki, so > it's easy to fix; I'll start the APIDocTool page). > > The remaining links returned by Google are even less > helpful, and on > page 2 we get a link to Shane Hathaway's post titled > "Zope 3 > Frustration"... > > Everyone expects the API documentation for a > framework to be highly > visibile in it's main web site. > > OK, I understand Zope 3 is undergoing a radical > reorganization right > now, which is a further push to descentralization, > making the idea of > locally generated API documentation even more > attractive. > > But I think we *also* need the API published on > Zope.org, for a few > advantages that the apidoc tool will never be able > to give us: > > - we need to be able to use Google to search the API > documentation > (even if the apidoc search worked perfectly, which > it doesn't) > > - we need to be able to collaborate with comments > and examples to the docs; > > The second point is really crucial. Just take a look > at this page, *please*: > > http://www.php.net/manual/en/ref.classobj.php > > Last year I had to do a project in PHP, and again > and again the > answers I was looking for were in the contributed > comments and > examples, even though their documentation is very > compreehensive. The > same amazing user participation can be seen in all > 23 languages (!) in > which the PHP API is documented. > > Contributing to Zope 3 docs must be made *much* > easier than being a > Zope 3 committer. > > Cheers, > > Luciano > ___ > Zope3-users mailing list > Zope3-users@zope.org > http://mail.zope.org/mailman/listinfo/zope3-users > ___ Zope3-users mailing list Zope3-users@zope.org http://mail.zope.org/mailman/listinfo/zope3-users
