Here is my new *cardinal rule of documentation*: *Thou shalt not put thine audience to sleep*
The *first *goal of documentation is to intrigue people so that they read on. Leo's present docs fail miserably in this regard. Imo, Leo's docs contain the right words, but in the wrong places. Summaries must be much shorter, with most details relegated to the background. Like this: *Use links*: Links can do a lot of heavy lifting--links to competitors, examples, and especially, links to "careful" definitions of terms and more complete explanations. Links should point to subsidiary pages that *aren't* part of the main narrative, not included in TOCs, etc. *Brevity*: Overviews must, of necessity, be *too* brief. Introductions are even allowed to create mild *confusion*, provided that readers sense that something intriguing lies ahead. *Summary* The present docs obscure the big picture, which is surprisingly simple. The new docs will* bring the highlights forward* by relegating everything else to the background. More pictures will also help. I have hopes for a fairly quick rewrite, because few new words will be needed. The 4x scheduling rule may apply, or not. Edward -- 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 https://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/d/optout.
