[Twisted-Python] Evangelism notes...

[Stephan Richter]

On Wednesday 04 May 2005 16:36, Itamar Shtull-Trauring wrote:
> On Wed, 2005-05-04 at 16:08 -0400, Mike C. Fletcher wrote:
> > Don't know if the other project will be rewritten as well.  Given
> > decision on this one, I'd imagine it will.  I'd also predict that
> > Twisted is now Techne non Grata wrt any new development where it's not
> > an explicit requirement (given that we're going to be eating costs on
> > rewriting a project to eliminate it).  Certainly I'll have a hard sell
> > going forward.
>
> Do you have any suggestions on how we can improve things? Besides "write
> more docs" which is basically always a given.

When we developed Zope 3, we put **huge** emphasis on documentation. As 
mentioned in the other mail, we made it a policy. Here are the things we did:

- We (mainly Jim) used a slide show and later plain text files to document how 
we imagined a feature to work. Basically we wrote Sci-Fi stories. Thus 
documentation was available before code.

- We also used a proposal process for larger features. This had a similar 
effect to the Sci-Fi presentation in that it documented the API before 
implementation. Many proposal authors made a point to update the proposal 
after the implementation, so that they would reflect the latest API. 

- We decided that Interfaces would be used for API documentation and public 
interfaces would always be found in the package's interfaces.py module, so 
people would always know where to go.

- We later developed a very custom (on purpose) API doc tool that would not 
only document interfaces, but their interaction with the system. For every 
interface you can see its adapters and views, or which utility provides the 
inspected interface. The doc tool was later enhanced to also provide 
documentation for any object, ZCML and plain text files.

- First we used regular unit tests for testing documentation, but eventually 
moved to file-based doctests, since they fulfill both XP requirements for 
tests: testing and documenting. I can't overstress the success. Every 
recently created or refactored package has now a README.txt file clearly 
documenting the API and it is never outdated, because it is part of the test 
suite. 

- We had two people write a book and find a publisher. My book is even 
semi-freely available as one can use it for non-commercial purposes.

So, what's next? This E-mail is not suppose to show what's Zope 3 did better 
than Twisted or vice versa, but demonstrate some concrete things that can be 
done to improve the documentation situation:

- I strongly suggest that Twisted starts using file-based doctests. I have 
demonstrated how this can be done with the current trial test runner in the 
following patch submission: http://twistedmatrix.com/bugs/issue1000

Also, I think twisted needs to start distinguishing between unit and 
functional tests.

- Develop a tool that clearly shows the available adapters for a given 
interface. epyrun will not pick this up, so it is important.

- Maybe it would be good to have a documentation sprint; since most (a lot) of 
the Twisted developers are in Boston, it would be good to do it here; I would 
be willing to come and help people getting started with writing file-based 
doctests.

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