On Sun, Aug 8, 2010 at 11:54 PM, ne1uno <[email protected]> wrote: > let me hasten to add, I am a strong believer in the insights > that I assume led to the creation of the original tangle/untangle > concepts, that is > keeping the docs with the code, now seen in a lighter form in doxygen, > javadoc, eudoc and others.
Thanks for these interesting comments. As I see it, documentation is a separate issue from the considerations that lead me to kill @root. The end of @root came when I saw that 1. The ability to modify multiple files is almost never useful, and is often an anti-pattern. 2. Ditto for the ability create sections from multiple parts, and furthermore, the syntax is a horror to describe and implement. 3. Leo's users were suffering greatly by the useless complexity of the @root docs. In retrospect, I see that I myself suffered greatly from @root. It was an unlimited energy sink. Worse, it complicated the Tutorial and Reference chapters. Perhaps most importantly, killing @root has lifted a fog of confusion from my eyes. As the new version of Chapter 6 makes clear, the benefits of Leo derive from outlines, *not* LP. I probably could not have written Leo in a nutshell while groping in that fog. The nutshell mentions no aspect of LP, and that has made it much stronger than other efforts to describe Leo. So yes, documentation is important, and as you point out, keeping it in sync is a seemingly hopeless task. However, the focus on documentation *instead of* outline structure is an anti-pattern. 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.
