On Mon, May 10, 2010 at 10:11 AM, Edward K. Ream <[email protected]> wrote:
> As I think about this project, I realize that the documentation will > be unusual in many respects. Indeed, it might be said to be the > antithesis of Donald Knuth's literate documentation. As I reread this remark, I realize that it appears to single out Knuth for criticism. That was not my intent. My apologies to him. What I was trying to say is that there is a huge difference in how I think of the present project compared to "traditional" documentation. I think the difference is that the present project has a specific audience and a specific purpose. Compare with typical docstrings. All the docstrings I have read are pretty much local rehashes of what a class or method does. Very few are "relaxed" in the sense that they discuss wider, and arguably more important issues. In contrast, in this project I am trying to tell Ville (or whoever else replaces me, it would be great to have several successors) all he needs to know to maintain and extend Leo. Unlike boring docstrings, there is an urgency and even excitement in these docs. Certainly I am more interested and excited about writing these docs than I ever have been before. Indeed, the project doesn't seem at all like a chore--I get to explain why what I have done is sound design. I also get to play with ideas for making the design and code even stronger. Edward -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/leo-editor?hl=en.
