[Twisted-Python] Questions about adding documentation

[Phil Christensen]

On Jul 31, 2009, at 2:15 PM, Kevin Horn wrote:
> Well, pragmatism is my basic reason for not liking wikis for docs. :)
>
> For me, it boils down to every time I've worked on or with a project  
> that used wikis for docs (assuming that the project is of at least  
> moderate size and has more than a couple of editors) that  
> documentation has been terrible.  It's ended up as a disjointed  
> mess, that's hard to navigate, and has a bajillion half-completed  
> thoughts, and lots of outdated cruft.
>
> Of course, some could say the same of (at least parts of) the  
> current Twisted documentation. ;)

Indeed; I wouldn't use those particular words because of their  
pejorative qualities, but I think the end result is that way because  
of the level of interest in maintaining documentation for a particular  
project. That's a different issue, but it is the reason why I'd like  
the documentation process to be easy for 'regular developers' (e.g.,  
not the proto-deities that make up the core devs ;-) to contribute to.

> It's not that there's anything wrong with wiki's per se, it's just  
> that they encourage "bad habits".  If there were a solid editorial  
> process in place, where someone was specifically responsible for  
> reviewing, editing, splitting, merging, and correcting documents,  
> then a wiki could probably work.  But I think it's easier to get  
> coherent docs using tools that encourage "good habits".
>
> Obviously my definitions of "good habits" and "bad habits" are  
> pretty vague...and not entirely spelled out even in my own mind.   
> Er, sorry about that...

Well, honestly, I don't disagree with you at all. A good set of  
documentation requires a great deal of work, and the amount of  
rewriting and fact-checking required is proportional to the amount of  
development going on. Twisted development has slowed somewhat over the  
years in a few areas, but it still moves quite quickly in others.

I don't see any documentation system making this go away. It will  
always have to be edited and revised, and it will often be out of date.

I think the issue is one of not 'scaring away' potential writers with  
a cumbersome process. Correct me if I'm wrong, but the current process  
for writing Twisted documentation is as follows (at least for people  
without commit access):

  1. check out a directory of Lore XHTML files
  2. make my changes or create a new file, making sure not
     to work against the sparsely documented schema ;-)
  3. generate a patch
  4. create a ticket, attach the patch
  5. bug someone on #twisted or the mailing list to do a review
  6. wait some unspecified amount of time
  7. code is merged into trunk
  8. wait for the live docs to be regenerated

Compared to a wiki:

  1. create an account (let's assume it's email-verified)
  2. write or edit some docs
  3. see your docs live immediately

Which do you think is going to be a more compelling process for people  
to get involved with? The first process is straight from the software  
development playbook, so it seems like a good idea, but I don't agree  
with the need for the same regimented process to exist w.r.t.  
documentation, especially when we are in such dire straights in that  
regard.

I'm not really married to the idea of a wiki per se, it's just that it  
seems to be the closest thing that provides contributors a low bar for  
entry and instant gratification by seeing their work online (and on a  
list of recent changes). Plus, it addresses a concern Ying Li just  
posted as I was writing this: you automatically get revisions, last- 
modified dates, and diffs of those revisions.

Yes, some of this documentation will not be of the quality we would  
like it to be. But it will still exist, which is a hell of a lot  
better than nothing. Plus, it gives the technical writers we  
occasionally see interest from some source material to work with in  
the first place, which has got to be helpful towards the ultimate goal  
of formally written core documentation.

-phil