Re: [Zope3-Users] Zope 3 API documentation needs a new strategy

2007-11-12 Thread Luciano Ramalho
On Nov 12, 2007 2:49 AM, Stephan Richter [EMAIL PROTECTED] wrote:
 On Tuesday 17 July 2007, Luciano Ramalho wrote:
  Everyone expects the API documentation for a framework to be highly
  visibile in it's main web site.

 It now is, thanks to some people finally finishing the static apidoc.

 http://apidoc.zope.org

Hooray!!! Thanks and congrats to all involved!

  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)

 How does a published APIDOC version not fulfill this requirement?

Who said it does not? My main point was that Google could not index
the apidocs installed in our development boxes. Now it finally can,
and that is great news!

  - we need to be able to collaborate with comments and examples to the docs;

 I do not think that an API reference should contain comments and examples.
 That's the role of other documentation. In fact, I believe reference
 documentation should *always* be autogenerated, otherwise information-rot is
 guaranteed.

Information rot is a problem, granted. But do not underestimate the
value of content reflecting the perspective of people who use the
framework even though they are not core developers of it.

  The second point is really crucial. Just take a look at this page,
  *please*:
 
  http://www.php.net/manual/en/ref.classobj.php

 A programming language is always much easier to document than a large
 framework, especially one that is dynamically configured.

Granted, but we are not afraid of challenges!

  Contributing to Zope 3 docs must be made *much* easier than being a
  Zope 3 committer.

 Well, you can always contribute to the Wiki, start your own page, or do
 whatever.

Of course those options are always available, but they totally miss my
point. My point is that, so far, the documentation of Zope 3 has been
written by the framework developers for the framework developers. That
is evident from the way it has been written, organized and (not)
published until now. But a successful framework has many more
programmers who use it than those who help develop it, and the
documentation should be open to contributions from the entire
community of users.

 However, just complaining about it will not improve the situation.

I am not just complaining. I am having a public debate with you and
anyone else who cares to join about ways to make the Zope 3 API more
accessible to people outside of the committers group. I see value in
this, and I am happy to note that you do too, otherwise you would not
have resurrected this thread which I started fours months ago. (Since
then I've also started contributing to the Grok project with examples,
docs and code.)

Don't get me wrong, Stephan: the dynamic APIDOC tool is fantastic, you
deserve many thanks from the community for it and for all of your
contributions to Zope 3 over the years.

Publishing the static APIDOC was a great step forward. At the same
time, Grok and Plone 3 are bringing lots of new programmers to the
Zope 3 world. I am sure the increased visibility and audience will be
of great benefit to the Zope 3 docs, if we make it easier for people
contribute.

Cheers,

Luciano
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users


Re: [Zope3-Users] Zope 3 API documentation needs a new strategy

2007-11-11 Thread Stephan Richter
On Tuesday 17 July 2007, Luciano Ramalho wrote:
 Everyone expects the API documentation for a framework to be highly
 visibile in it's main web site.

It now is, thanks to some people finally finishing the static apidoc.

http://apidoc.zope.org

 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)

How does a published APIDOC version not fulfill this requirement?

 - we need to be able to collaborate with comments and examples to the docs;

I do not think that an API reference should contain comments and examples. 
That's the role of other documentation. In fact, I believe reference 
documentation should *always* be autogenerated, otherwise information-rot is 
guaranteed.

 The second point is really crucial. Just take a look at this page,
 *please*:

 http://www.php.net/manual/en/ref.classobj.php

A programming language is always much easier to document than a large 
framework, especially one that is dynamically configured.

 Contributing to Zope 3 docs must be made *much* easier than being a
 Zope 3 committer.

Well, you can always contribute to the Wiki, start your own page, or do 
whatever. However, just complaining about it will not improve the situation.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
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

2007-07-18 Thread Torvald Bringsvor

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


Re: Vedr. [Zope3-Users] Zope 3 API documentation needs a new strategy

2007-07-18 Thread Benji York

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


Re: Vedr. [Zope3-Users] Zope 3 API documentation needs a new strategy

2007-07-18 Thread Luciano Ramalho

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

2007-07-18 Thread Andrew Groom

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


[Zope3-Users] Zope 3 API documentation needs a new strategy

2007-07-17 Thread Luciano Ramalho

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