Stephen, Thanks for your comments. I've put some of my responses inline.
Stephen wrote: " When I'm writing documentation, my problem isn't in what to write... but in trying to imagine a fictional person and what they'd want to read. In those constipated moments, I'd love to have someone sitting there asking me any questions, to which I'd happily type the answers." It sounds to me like you're talking about user input. This is a great idea that I've never really thought about. Now we need to think about how you can get this user input. I know that I often see the same questions on the user mailing lists again and again. These questions would be great candidates for documentation, or at least a FAQ. In order to capitalize on this source of user input a developer of administrator must do more than simple answer the user question, they need to move the question and answer to another form of documentation. Another idea is to just ask the users what part of the program they would like to know more about. I might have to try this to see what type of user input I get. The only problem with this method is that users already need to know something about your program features and the basics of how your program works. Stephen wrote: " Another piece of the puzzle could be integrating bug reporting into IRC, where someone types in a complaint and that section of text is marked with a ticket. The ticket can be resolved with further chat, or automatically percolated upwards into a more formal ticket tracking system." I've been working a little with the bug tracker at SourceForge the last couple weeks. It is a nice system, but I struggled with some aspects of it. For example, a lot of the "bugs" in the tracker were'nt bugs at all, or were bugs based on the users computing environment, or were bugs in older versions of the program. I found that a lot of the bug reports lacked basic information like the version of the program and the user's operating system type. It's almost like we need a person guarding the gate of the bug tracker. :] Or maybe I need to write a simple "Guide to Submitting Bug Reports". Stephen wrote: "Some entertaining ideas come to mind about integrating forums and chat too, and I'd love to have something like pair programming or shared editors where people can watch code being edited, with questions/comments/corrections to one side." I like the idea of a way for programmers to log comments and questions in or "on one side" of a source code file. I often copy a source code file that I am interested in so that I can add my own online comments. I think this would be a really great tool. It would allow someone else to view my comments and questions about the contents of a source code file without cluttering the source code itself with unnecessary comments. I bet I can cook something simple up in a language like Python that ties comments and questions to the line number of a source code file. Thanks for the great ideas and discussion Stephen. Landon -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of stephen white Sent: Saturday, January 27, 2007 5:15 AM To: [email protected] Subject: Re: [Geowanking] radically improving open source software On 27/01/2007, at 5:48 AM, Anselm Hook wrote: > At a slight right-angles to the above; I suspect IRC is the secret > engine of the net... ongoing persistent conversation is where a group > begins to improve its awareness of itself and its aspirations... I was pleased to see that Landon Blake continued the thread, as this is a group where the old arguments wouldn't be re-hashed. We're all striving for new approaches to old problems. I agree with you that the key to the software documentation problem is in IRC and ongoing persistent conversation. When I'm writing documentation, my problem isn't in what to write... but in trying to imagine a fictional person and what they'd want to read. In those constipated moments, I'd love to have someone sitting there asking me any questions, to which I'd happily type the answers. When I look at a source code tree, for example: parser/state.c parser/statecomment.c parser/statecomment.h parser/statecomment_test.c parser/statequote.c parser/statequote.h I can see that these could be IRC channels, with people sitting in the bits of code that they know. They would know how their code connects to other bits of code, so someone going over the source tree can move from channel to channel. If the channels were logged into raw captures, then quick searches could handle much of the routine. At a layer above raw chat, the chunky nuggets of wisdom can be pulled out for a more nutritious meal. The next layer above that could be the documentation in reader- friendly format. Eg; from the top-down: Project documentation (PDF?) Module documentation (multiple - DocBook?). Module notes (more current, less readable - wiki format?). File notes (IRC + wiki?). Files (IRC + logging?). Another piece of the puzzle could be integrating bug reporting into IRC, where someone types in a complaint and that section of text is marked with a ticket. The ticket can be resolved with further chat, or automatically percolated upwards into a more formal ticket tracking system. Some entertaining ideas come to mind about integrating forums and chat too, and I'd love to have something like pair programming or shared editors where people can watch code being edited, with questions/comments/corrections to one side. Between the talents this group has, we should be able to whip together an example mash-up quite quickly to see where this could take us? Of course we would put in the various geo* improvements (red dots blinking in America as people type!) to cater for our interests. :) -- [EMAIL PROTECTED] _______________________________________________ Geowanking mailing list [email protected] http://lists.burri.to/mailman/listinfo/geowanking Warning: Information provided via electronic media is not guaranteed against defects including translation and transmission errors. If the reader is not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this information in error, please notify the sender immediately. _______________________________________________ Geowanking mailing list [email protected] http://lists.burri.to/mailman/listinfo/geowanking
