reST, mechamisms? (was Re: [Zope3-dev] Z3 documentation)

[Jeffrey P Shell]

On Wednesday, April 2, 2003, at 09:50  AM, Stephan Richter wrote:

> On Wednesday 02 April 2003 10:41, Jeffrey P Shell wrote:
>> What would I / we need to do to start moving forward?
>
> Please, please implement/integrate reST in Zope 3. I just talked to 
> Jim, and
> he said he would love someone to do this!

What needs to be done to start off?  A proposal?  A branch?  Is there 
anything existing I could/should look at before starting?

> BTW, I will make sure you are bale to use reST from the Online Help 
> then!
>
>> And while narrative documentation is being developed in the Wiki right
>> now, there are plans to move it to files/CVS at some point before 
>> final
>> release, right?  I think it's important to tag and release
>> documentation in near-sync with shipping code.  I think it's great 
>> that
>> I can travel back in time to Python 1.6 documentation on the rare 
>> cases
>> I still need to.
>
> Well, I would prefer the documentation to live in the Wikis, for all 
> of the
> reasons I posted before. Wikis have versions too. And notice that most 
> of the
> Wiki based documentation would not be as suitable for files anyhow, 
> e.g. I
> would never want to write a Cookbook in CVS files.

I've never had a good experience with documentation kept in Wikis.  I 
find them to be a good supplement, but after a few years of use, the 
information is so mixed between relevant and irrelevant that I often 
end up leaving in frustration.  They become unbelievably hard to 
navigate and are full of broken promises - links to barely filled out 
or useless pages.  I've always wanted to learn Squeak, but get so lost 
in its Wiki that I can never stick with it.  ZPatterns was the same way 
- there was very useful information in the Wiki, but it got so tangled 
up that narrative was lost - in many cases it felt like there were more 
links than words.  requiring a lot of clicking and backtracking in 
order to understand a simple concept.

If we can keep that from happening, then I don't mind.  People say a 
Wiki is as good as its gardeners, but I somehow keep coming across all 
the weeds.  :\

So, I think its a good supplement, but I feel that it's no replacement 
for real managed documentation.  I don't want my feelings of 
frustration with other documentation wikis to be felt by others.

Those are just my concerns.  There's a lot of good things that a Wiki 
gives, I'll grant that.  But so much care has to be taken to ensure 
that:

- Documentation is always current, but doesn't go
   beyond shipping versions of the code.  If we're
   six months away from Zope 3.1, but documentation
   already reflects Zope 3.1 changes and its
   causing breakage or yielding unexpected results,
   people will get frustrated and leave.  Yet we
   do need to be able to update docs while new
   versions of the software are in development
   so that there's no big flurry of activity at
   release time to try to update.

- If the current version is Zope 3.3, for example,
   but someone is still running Zope 3.0 and can't
   move beyond it for various reasons and needs
   to do maintenance, they should be able to easily
   find the Zope 3.0 documentation and stay within
   that range.  Versions on single documents won't
   help here.

   Good local online help and API documentation
   might be a way to mitigate this risk.

- Links in documentation don't take people to
   antiquated design documents and proposals that
   don't reflect current code without EXPLICIT
   warning.  It's very frustrating thinking you'll
   find documentation about how the event system
   works and instead find a two year old document
   discussing how one MIGHT work.  This is my
   biggest concern if the documentation is mixed
   in with the rest of the code, as it was a
   frustration I felt early on.

- No pages titled "ObjectHub" whose only content
   is "An object hub is a hub with links to objects".
   I see pages like this (and have authored them
   myself) where the author might think they'll
   come back later and fill things in, or hope
   someone else will, and many months later it's
   still an empty page.

- Pages are narratives, and not just a couple of
   paragraphs full of links to more pages with just
   a couple paragraphs full of links.  It's too much
   clicking, backtracking, and clicking again, just
   to grasp a basic concept.

I think most of these are pretty common sense things [1], but they 
still seem to get forgotten.  :\.  I just wanted to raise these issues 
now so that we're mindful of them.

[1] http://zwiki.org/ExcessiveLinkingConsideredHarmful

> However, I really want the OnlineHelp to live in reST space. In fact, 
> the
> reason I have not written any more OnlineHelp screens is because of 
> the lack
> of reST.