I am now in the midst of a wonderful revision of Leo's docs in LeoDocs.leo. I'll finish this work later today, but I'm so excited about it that I wanted to tell you about it now.
The revision eliminates all minor details previously found in the Release Notes and What's New sections. Important items have been moved to the History of Leo section, where they are easily visible. This section now deserves it's own chapter. This chapter will clearly indicate the year that each major release went out the door, something that should have been done long ago. I have learned much from this project. I had forgotten how much work and innovation it took to put sentinels *into* external files so that reading such files is bulletproof. We have now come full circle. @clean removes sentinels from external files, but the Mulder/Ream update algorithm depends on reliable sentinel technology! This new reorg will make LeoDocs.leo much more useful for users. Truly important documentation will stand out clearly in the History section. Part of this project ensures that all new commands from Leo 4.0 forward are actually documented in the Users Guide. Once that is assured, the entire What's New section will be deleted. ==== Cleaning the attic As I was contemplating this work, I noticed a reluctance to truly clean the attic. What if some minutia of a release note should be needed later? Such reluctance may be natural, but it is not our friend. The *present* release notes will contain all the minutia, but they will be edited out when transferred to the History chapter. Once a new release comes out, *nobody* cares about the details of the previous releases. Old release notes will simply be deleted. In particular, *nobody* cares about old bugs. We only care about the bugs fixed in *this* release. Leo's bug trackers retain all details unlikely event somebody wants to do archeology. In short, less documentation is more useful documentation. I should have seen this long ago. This principle should help Leo's users greatly. Edward P.S. I noticed a similar reluctance to clean the attic when working on leoAtFile.py. As with the documentation, attachment to useless code is harmful. The old code added nothing to Leo. Worse, it obscured what is really going on *today*, thereby making it harder for future maintainers. Git provides a permanent record in the extremely unlikely event that the old code becomes important. EKR -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/d/optout.
