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

[Stephan Richter]

On Wednesday 02 April 2003 13:20, Jeffrey P Shell wrote:
> 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?

No, no proposal needed this time, unless you want people to help you with some 
design decisions. Basically I want the same comfort as in ZPTPages. 

help  = RSTFile(<PATH>+'helpfile.hlp)
help(request)

> 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.  :\

I agree; this is the reason I try to keep it organized. I did some gardening 
in November, I guess it is time to do this again. 

> 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.

So far the Zope 3 core developers have a really good experience with Wikis; I 
guess we are decent gardeners.

> - 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.

Well, right now we are not at this stage of the game. Wikis are intended to 
reflect current and scifi behavior. I have nothing against moving to more 
formal tools later, but currently this is not needed, and we will have much 
more input using Wikis for now.

> - 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.

But we are not there yet (for quiet a while). We can talk about these issues 
in 8-10 months.

> - 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.

Well, we can prefix all documentation with 'Doc'.

> - 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.

Well, it is up to the documentation team to keep track of that and fix it. 
This is not a danger of the Wikis but of all documentation.

> - 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 disagree. I have written successfully docs in Wikis which do not suffer that 
shortcoming. In fact, if links are used wisely, they can have a positive 
effect, since they lead you into deeper discussions.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training