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