[Zope-Coders] Documentation (was CallProfiler and Refresh)

[Chris McDonough]

I understand your pain.  So as not to go insane duplicating content, I
would suggest this:

- Create UI help screens for each view introduced by CallProfiler. 
(ones that say, "id is the object's id" and other relatively stupid
stuff, spending the lion's share of the time on form elements and
display data elements that need to be explained).

- Add a long comment (or several comments) to the Zope Developer's Guide
Testing and Debugging chapter
(http://www.zope.org/Documentation/ZDG/TestingAndDebugging.stx) with a
description of what CallProfiler does and an example of how it is
helpful when trying to run down performance issues.  I will "fold this
in" to the next docs release.

- Create a single "narrative" help topic (one that is not connected to
any particular mgmt screen view) inside the CallProfiler that points to
the ZDG chapter's URL (e.g. "CallProfiler is a diagnostic tool that
helps do the following (yada yada...).  For the latest information on
how to effectively use CallProfiler, see
http://www.zope.org/Documentation/ZDG/TestingAndDebugging.stx").

Does that sound reasonable?

The dichotomy between the help system content and the Book content is
something that I'd like to have the time to solve, but we've not been
able to commit to spending any time on this (I offered to rewrite the
help system for 2.6, which would have done this, but Brian spared me by
nixing the proposal ;-)

On Tue, 2002-05-28 at 12:47, Toby Dickenson wrote:
> >     There needs to be at
> >     least basic help for each of the views and some fodder for
> >     the online Zope book before it can be merged / go into a
> >     release. (Note that it's usually OK for the Zope book fodder
> >     to be a mildly reworked and shined up version of the help
> >     material).
> 
> I am a little frustrated by this approach to documentation. I recently made a 
> change to dtml that affected the documentation, and found *five* different 
> copies that needed the same change. 
> 
> Do we really need even two different copies of the same documentation?
> 
> 
> 
> 
> _______________________________________________
> Zope-Coders mailing list
> Zope-Coders@zope.org
> http://lists.zope.org/mailman/listinfo/zope-coders