[Twisted-Python] Questions about adding documentation
phil at bubblehouse.org
Fri Jul 31 16:01:03 EDT 2009
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
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.
More information about the Twisted-Python