[Twisted-Python] Documentation Guides (was: In Defense of Taps)

[Kevin Turner]

On Fri, 2003-02-14 at 04:42, Glyph Lefkowitz wrote:
> Thanks for that bit of information: after thinking about those categories some
> more, I've realized that an upcoming rewrite of the website needs to address 4
> audiences[...]

I was at what one might consider a brainstorming session for presenting
on-line documentation[1] the other day, and people came up with this
idea:  When you're about to embark on a trip through foreign territory
(i.e. Framework X documentation), you may want to hire a guide who knows
the area to lead you through it.

...I think I need to stop and provide a bit of context here.  The topic
was documentation with in-line comment systems, like you see in the Zope
Book now.  Someone postulated that they might like it better if instead
of being constantly bombarded by comments from all sorts of people, they
could filter it down to just one guy who commented frequently, to get a
single consistent voice.  The concept was also likened to the
"commentary track" that comes with the DVD version.  Okay, now back to
wild analogies...

Which guide you select depends on your experience level and what you
want to see.  In any case, you and your guide cover pretty much the same
ground as everyone else, but where you go into detail and from what
direction things approached will vary from guide to guide.  

or, in Twisted speak, 
self.howto = components.getAdapter(howto, IHighLevelNetworkDeveloper)
although at the aforementioned discussion, people were talking more
about another dimension, the one ranging from Newcomer ("put *lots* of
comments in those examples, please") to Old Hand ("just tell me what
module to look at").

I'm not convinced these ideas have any practical value.  It seems
incredibly expensive to me to develop useful commentary tracks[2] for
every class of reader, effort that could be directed to fortifying the
core documents.  But it's what I thought of when reading this "we need
to make documentation approachable for X, Y, and Z, and does this go
before or after dirdbm."



1: http://groups.yahoo.com/group/porpig/message/274

2: unless, the theory goes, you have such an active community that these
things just write themselves, and then some collaborative filtering
system picks out what's good for you.  Hah!

-- 
The moon is waxing gibbous, 92.1% illuminated, 12.1 days old.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://twistedmatrix.com/pipermail/twisted-python/attachments/20030214/649fc366/attachment.pgp