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

[Jeffrey P Shell]

I don't know if this is the right time to bring this back up - but 
what's the story of reStructuredText and Zope 3?  I've had great 
success with using reST for both user and technical documentation.  I 
think it offers some directives and other helpful features for writing 
long docs, complete with in-document tables of content (something that 
the Zope 2 book desperately needs - navigating the "Advanced ZPT" page 
can be a daunting exercise sometimes).  I think Jim gave reST his 
blessing a few months ago, but its use has been vague.

Even if we don't use it right away for narrative documentation, it 
could be helpful for use in the help-files.  A recent (relatively) 
change to reST has been in its "interpreted text roles" system, a way 
of doing specialized markup.  This could be beneficial for Zope 3 by 
making it easy to hi-light Interface or API references that could be 
turned into real links later without having to deal with URI's in the 
documentation itself.

Interpreted text is text between single backticks, like `this`, with a 
role at the beginning or end encased in colons, such as::

     See :interface:`zope.example.interfaces.IFoo`

If this particular role is used constantly, I believe it's pretty easy 
to set "interface" as the default role, so that the above can be 
compressed to::

     See `zope.example.interfaces.IFoo`

although this could crash up against the reST docstring formats default 
roles documented in PEP 287.

These interpreted roles are a transform and are agnostic about the 
output - the above example would most likely add a reference node to 
the document tree with a URI reference to either local help or to Zope 
API documentation on the server.

In any case, it might be good to start evaluating the real needs for 
the online and ZCML help files as the code base seems to be nearing a 
point where we're running out of room to punt - "just write some help, 
we'll deal with it later".  I think we should start writing that help, 
but also start dealing with the mechanisms now so that by the time we 
hit beta there might at least be something usable.

What would I / we need to do to start moving forward?

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.

On Wednesday, April 2, 2003, at 08:03  AM, Stephan Richter wrote:

> On Wednesday 02 April 2003 10:02, Jeffrey P Shell wrote:
>> On Wednesday, April 2, 2003, at 02:13  AM, Steve Alexander wrote:
>>>> 2. What is the primary target audience? E.g. Zope2 users? Zope2
>>>> developers? General readers outside the Zope community? While well
>>>> designed docs can certainly address the needs of multiple groups, 
>>>> it's
>>>> generally helpful to identify a primary target.
>>>
>>> The main documentation should assume no knowledge of Zope 2 from the
>>> reader. Many users of Zope 3 have not used Zope 2.
>>
>> I think that Zope 3 is different enough that even Zope 2 users would
>> benefit from clear documentation removed from previous contexts.  And,
>> as you point out below, I think that a "Zope 2 to Zope 3" translation
>> guide would be nice, and could actually benefit by being able to focus
>> on documenting the differences and telling the story in Zope 2 terms
>> while not having to document all of Zope 3 at the same time.
>>
>>> There could be other documentation specifically to allow people to
>>> reuse their knowledge of Zope 2 in the context of Zope 3.
>
> I actually outlined the documentation this way already in the Wiki. 
> BTW, I
> agree with all the suggestions and thoughts on this thread so far.
>
> Regards,
> Stephan