[ZDP] Policy -- Docs link to source

[Loren Stafford]

I'd like to suggest, that, as a matter of community policy, all
documentation contain links back to the relevant source-code files. The goal
is to make it possible for someone reading a source file to conveniently
find all relevant documentation about that file (including commentaries in
email lists and other forums).

At the very least, links could be implemented as a textual mention of the
source file. In that case, a search on the source-file name would bring up
all relevant documentation.

For example, the Chapter 4.II.2 "Zope Publisher" on
http://zdp.zope.org/guide/ZBook/Outline/Chapter_2/Part2_4/Part24_2
could terminate with a brief paragraph saying that the ZPublisher is
implemented primarily in ../lib/python/ZPublisher/Publish.py. That way a
reader of Publish.py could find the overview of Chapter 4.II.2 when
searching on "Publish.py". Another example is at the bottom of my "HowTo:
ZClass Properties" (http://www.zope.org/Members/lstaffor/zProperties). I
recently added the source-file links after doing some research in the
Properties source code, and wishing I could read everything that had been
written on the subject. Of course, I could search on "property" or
"properties", but that would not result in as focussed a set of results.

Documents that are part of some Zope document-management application might
even have methods that return lists of relevant source files. That way
special source-documentation catalogs could be built (topics?). I am not
sure how far we need to go in that direction, though.

Ideally the technique for linking and cataloging could be shared by official
documents as will as ZDP and individual contributions (such as How-To's). If
the technique cannot be shared, at least the policy should be.

An idea worth pursuing?

-- Loren