Troubleshooters.Com Presents

Troubleshooting Professional Magazine

Volume 3, Issue 11, November 1999
Outlines: The Do Everything Tool
Copyright (C) 1999 by Steve Litt. All rights reserved. Materials from guest authors copyrighted by them and licensed for perpetual use to Troubleshooting Professional Magazine. All rights reserved to the copyright holder, except for items specifically marked otherwise (certain free software source code, GNU/GPL, etc.). All material herein provided "As-Is". User assumes all risk and responsibility for any outcome.

[ Troubleshooters.Com | Back Issues ]

Hot off the presses: 5/21/2001
High Quality Open Source Outliner for Linux
Vim version 6
Read about it here!
You can download the GPL VimOutliner Project


Editors Desk

By Steve Litt
"I Can't Tell You Why" played from a distant radio. A several-times refilled cup of McDonalds coffee sat on the table. I sat back and reflected on the moment. Disco still reigned supreme, but Top 40 was taking a turn for the better with songs like Pink Floyd's "The Wall" and Starship's "Sarah". Jimmy Carter was president, and probably would be for four more years. It was April of 1980. I was in McDonalds on the north side of Chicago.

McDonalds had been my office for the past 3 days. Same as it would be tomorrow -- for however long it took. Planning a move from Chicago to Los Angeles isn't something you do in a couple hours. Not if you want to succeed. I had no intention of crawling back to Chicago, tail between my legs, with my friends chirping "see, I told you you wouldn't like it". Nope, I was planning it just right, so the only visits I'd make to Chicago would be just that -- visits. On my McDonalds table, crowded with pencil writing and coffee stains, was my outline.

Late April 1980 was a crossroads. In less than a month I'd leave my native Chicago for L.A., where the sun was brighter, the life more laid back, the salaries higher, the opportunities greater. What do I take? What do I leave? What do I sell? What do I need to do to wind up my affairs? What arrangements to I need to make for my new life on the West Coast. I turned to my old friend, the outline.

Outlining was tough in those days. There was no insert or delete, no copy or move. You did it double-space. In pencil. You tried to make sure your changes didn't exceed the length of what you erased to make room. You hoped your eraser didn't go right through the paper. You tried your best. And when it got too marked up, you'd transcribe it to new paper. That last week in April, I was a fixture at McDonalds. The outline reached a size of five or six pages. It was right on the money, allowing me to complete all preparations in two weeks. On May 15, 1980, my noisy, rusted out 1972 Chevy Impala aimed west and drove.

Like so many before me, I rumbled down the highways paralleling the old route 66 with nothing but an ancient overpacked car and the age-old dream of jobs and sunshine where old 66 ended at a sign reading "Santa Monica Pier". My future stretched before me, unseen. No way of knowing that Jimmy Carter was in the last 10 months of his presidency, or that disco would be dead in a year.

I couldn't guess that my stay in L.A. would span 18 years, during which personal computers would change from solder and assemble to bare-bones CPM to handy DOS PCs to friendly Windows machines to powerhouse Linux boxes. No way to know that within 6 years there would be computer tools to make creating, changing and storing outlines a snap. How could I guess that within 4 years I'd change from an electronics tech to a computer programmer? Or that within 10 years I'd add "author" to my list of professions, and that within 15 years there would be a profession called "Webmaster" and I'd be one. How could I know that I'd someday use computer assisted outlines to design books, computer programs and websites?

Imagine sitting next to me in that rusted up 72 Chevy, listening to Christopher Cross's "Fly Like the Wind" and reports of the Mount Saint Helen's eruption. Imagine telling me that in 2000 I'd be working on a "Linux Box" and listening to a radio format called "hot adult contemporary" because Top 40 had died. You'd have seen cynical disbelief on my face. If you'd told me there would someday be computer programs to ease creation and modification of outlines, you might have seen a wistful smile. But if you'd told me that at the turn of the millennium I'd be using outlines to plan my projects, I'd have simply said "obviously".

This issue of Troubleshooting Professional Magazine discusses how to use outlines and outline processors to make a technologist's life easier. So kick back and relax as you read this issue. And remember, if you're a Troubleshooter, this is your magazine. Enjoy!

Steve Litt is the author of Troubleshooting Techniques of the Successful Technologist. He can be reached at Steve Litt's email address.

Software Design With Outlines

By Steve Litt
Let's start the discussion with structured programming. Although OOP is obviously superior for large software projects, there's an amazing amount of structured programming still being done. While OOP is more scalable, it requires much more time and effort to design. If you want to whip out a 1000 line program in two days, you go structured.

Top down structured design is an outline. Traditionally it's been done as diagrams, but rest assured it's an outline. Break the program into tasks. Break each task into subtasks. Break down each of those subtasks. Keep breaking it down (functional decomposition) until the entire program is represented by trivially obvious subtasks. Then code it, debug it, and deploy it.

The "Code Readability Throughout the Ages" article in the August, 1999 Troubleshooting Professional Magazine advocated use of a merged design/code method alleviating the need for outline processors. That works for reasonably straightforward jobs. But when there's excessive trial and error, with the designer "trying out" various routines, the outline processor shines. A subroutine and its entire tree can be quickly moved from place to place, decomposed or merged. Plus the outline view makes the program structure much more obvious than even the most readable source. So on straightforward projects use the method described in the 8/1999 article. For tough projects, use an outline processor.

What About OOP?

The outline processor is not as perfectly matched to OOP design as to structured, but it's still an essential tool. First, every class contains methods and variables. Some of the methods call other methods (hopefully in the same class or in a very select group of other classes passed in through arguments), and some of the variables are objects. These are hierarchies suited to outline representation. In spite of our best intentions, some class methods are long enough that they must be designed with functional decomposition. Enter the outline processor.

OOP programs are combinations of interactions, rather than a time domain flow of tasks. For that reason they're better represented as diagrams at the high level. At lower levels, outline processors are a valuable design tool.

Steve Litt is the author of Troubleshooting Techniques of the Successful Technologist. He can be reached at Steve Litt's email address.

The Outline Processor as a Writing Tool

By Steve Litt
THE classic example of outline use is in the writing process. It's taught in grade school (or it should be, and if it isn't complain to the school board). Every "how to be an author" book stresses outlining the structure of a book, short story, or website before writing it. Believe it -- it's true!

Writing is remarkably like software development. The role of design goes up exponentially with the size of the project. A 50 line program is simply typed in and debugged. A 500 line program requires a few hours of design. A 5000 line program requires a week or two of design. The biggest programs I've ever single-handedly written comprised maybe 25,000 lines and required a couple months design -- typically more than the coding time.

Similarly, writing something as short as this Troubleshooting Professional Magazine requires no design, other than deciding on a theme and thinking up some articles. Past maybe 5000 words (typically 10 pages), a little design is required. At 30 pages there's a need for a formalized design that can take a day or two. At 150 pages I'd recommend a week or two of design before writing. My latest book, "Rapid Learning: Secret Weapon of the Successful Technologist", weighs in at 320 pages. The table of contents (TOC in writerspeak) took six weeks to design. Time VERY well spent. The quality of the design shows up in the quality of the finished book. The book's really good and well organized.

And that quality probably cost me only 2 or 3 weeks, because much of the extra design time is compensated by the quicker writing achievable with a well designed TOC. That's because an organized TOC eliminates most of the big three boogiemen in book writing: Chapter interdependencies, forward references and redundancies.

Chapter Interdependencies

A book is surprisingly similar to a computer program. As it gets larger, the development and debugging speed depend not so much on the number of components, but the number of interactions between them. If every chapter must know every other chapter's business, the book will probably never be completed, and if it is, it will be confusing to the reader. Ideally, each chapter should stand entirely on its own. It takes between a day and a week to write a 15 page chapter (some authors are much faster, some are much slower, but this range encompasses most professional writers). That means a 300 page book can be written (not including design) in 20 days to 20 weeks. BUT...

If many chapter dependencies exist, each change to one chapter requires changes to each of the other 19 chapters. Each of *those* changes require further changes. Add in the fact that switching chapters around late in the game requires chapter number changes on all inter chapter references, and the entire writing process bogs down. Chapter dependencies are the kiss of death to a large writing project. To the extent possible, arrange and rearrange the outline, using the outline processor, to eliminate chapter dependencies before the first paragraph of prose is written.

Forward References

In most books (as opposed to websites), it reasonable to assume that the reader has read the previous chapters before this one. Since the reader has that knowledge, the present chapter stands on its own. Contrast this with use of knowledge to be covered in a future chapter. The reader must be pointed at that chapter and told to read it, then come back. This creates an unacceptably hard to understand book, and must be avoided.

That's not always so easy. Consider two concepts that depend on each other. One must come first. There are different ways to solve such a problem. As an example, consider the concepts of Mental Model and Divide and Conquer in Troubleshooting. The Mental Model must be designed to best show where to perform Divide and Conquer tests, while Divide and Conquer relies completely on the Mental Model to locate such test points. There are a number of solutions to such a dilemma.

In my book, Troubleshooting: Tools, Tips and Techniques I solved it by serving up each on a "need to know" basis, with four successive chapters titled The Mental Model, Divide and Conquer 1, Binary Search, Divide and Conquer 2, Where to Draw the Fences, and Mental Model Revisited. This layout retains the portrayal of these two concepts as distinct concepts, rather than a package deal, by presenting enough of each to serve as a point of reference for the next.

I could have gone the other way, portraying them as a package deal. Introduction to Mental Model and Divide and Conquer, Binary Search, Real World Divide and Conquer Strategies, and Creating Mental Models. Under this scenario, the two concepts would grow together.

I could have made one subservient to the other. In fact that's what happened as my tools centric documentation evolved into a process centric one. Today I describe the Mental Model as a component of Step 6: Narrow it Down.

All of these work, but none are painless. The important thing is to do all the experimentation in the outline, using an outline processor, rather than waiting until the writing or proofreading step and moving whole chapters or major sections around.


This is the least destructive of the three boogie men, and in fact some redundancy is always necessary. Just keep it to a minimum.

Redundancy has many of the same problems and justifications as database denormalization. A little redundancy in a chapter can eliminate convoluted interchapter lookups, some of which might be forward references. Redundancy can serve to "drive home" an important point. And just like a denormalized database, redundancies require tracking and synchronizing of all copies of the information. Like the denormalized database, redundancies puff the size of the book, which may be a problem (especially in mail order where binding and shipping costs are substantial).

Redundancies become obvious during the outline design stage if sufficient design time is allocated. Redundancies sometimes require major reorganization to solve, but often require only the elimination of the later copy (maybe with a backward reference), or keeping both copies but having them show a different facet of the subject. The important rule is to find and fix redundancies during the outlining stage.

Sometimes, even after prolonged consideration of the outline, redundancy is the only way to prevent a chapter interdependency or a forward reference. Redundancies are by far the lesser of the three evils.

Outlines and Websites

Take it from me, writing for a website is much easier than for a book. Hyperlinks free the author from the requirement of eliminating forward references, and make it much easier to make each page and subsite modular. Many websites, including Troubleshooters.Com, are structured in a hierarchy for easy organization and navigation. As long as use of subdirectories (for subsites) and pages are done intelligently, adding a new section requires little design.

That being said, Troubleshooters.Com had the good fortune of getting in the game early, when a simple site could attract big traffic. It's grown much as a small town grows through the years -- in an intelligent, planned way, but maybe not the way it would have been designed from scratch. A new website today must be voluminous to attract traffic, and must be well organized. Enter the outline.

Websites come in many architectures. There are series sites where each page leads only to the next page, a sort of HTMLized book. There are "rings" where you go back or forward, and can go completely around. There are "web" architectures where every page connects to every other page. There are hierarchies, where subjects branch out. There are web-hierarchy hybrids, which allow a departure from orthodox hierarchy in order to put needed information a single click away.

To the extent that your new site is hierarchical, its ideal design tool is an outline processor. Start with the home page, and list its resources in order. Resources are headings, graphics and links. Find a way of symbolically differentiating between the three, and also find a way to represent when a link points to a subdirectory. Now outline the site, keeping in mind the qualities of modularity, ease of finding, quick retrieval (watch out for those 200K pages). Identify which pages are really part of a series, and organize them accordingly.

Writers Cramp

Writing the 132 page "Troubleshooting: Tools, Tips and Techniques" consumed 18 months of my time part time  in 1989-1990. Writing the 320 page "Rapid Learning: Secret Weapon of the Successful Technologist" consumed less than 4 months (almost full time) in 1999. Admittedly I devoted more time per day to the latter book, but that's not the major difference.

The difference was my use of outlining. In the Troubleshooting book, I outlined down to maybe the sub-subsection, reviewed each chapter for a few minutes, and went on. As the writing process unfolded I repeatedly discovered serious structural flaws (chapter dependencies, forward references and redundancies) that needed correction, and spent a great deal of time cutting and pasting huge chunks of text and headings. The month I saved on the outline cost me eight.

Contrast that with the Rapid Learning book. There I went down six headings deep, and took a few weeks after outline completion to evaluate and reorganize. The actual writing task turned out to be 5-6 weeks of full time writing. What a difference design makes.

Steve Litt is the author of Rapid Learning: Secret Weapon of the Successful Technologist. He can be reached at Steve Litt's email address.

Life Planning

By Steve Litt
Isn't the title of this article nauseating? Sounds like an AM radio show where a pop psychologist belittles all his callers. Or maybe an "investment expert" who chastises his callers for compounding their assets too slowly (and then hides out during stock market crashes). Relax. This article is just what it says -- how to use outlines as a tool for planning your life. The cross country move discussed  in the Editor's Desk article is an excellent example. This article contains other examples.

Business Trip

Consider planning for a business trip: A list like the preceding guides the planning of the trip, and converts packing from a half day affair into an hour before leaving the house. It also reduces the likelihood of forgetting something.


I've been married almost 10 years but I still remember that wedding planning was a HUGE project. If it were professional instead of personal you'd demand a month's salary to do it. Except you need to start more than 6 months in advance. Rent the reception hall. Procure place of worship, park, or back yard. Invite the bridal party. Make arrangements for gowns and tuxes. Flowers. Food.

Sylvia did 90% of our wedding planning. Had I planned it it would have been a little room with our parents and Sylvia's sister, brother in law and niece. For the tiny bit of planning I did (and 3% of a wedding is still a huge job), I used an outline. It made it manageable. And if for some reason I have a more major part in a future wedding (I have two daughters), I'll use an outline.

Long Term Strategy

"Where do you want to be in five years?" That's a question we all grapple with. And it's a much more difficult question than "make your dreams come true" popular press authors and speakers make it out to be. The preceding is very simplistic, but the idea is clear. Not only is an outline great for hard planning, but it's also a great strategic think tank that can be changed and adapted through the years.

To Do List

The lucky ones have linear To Do lists with five or six items every day. A pencil and paper suffices. This type of life is rapidly going the way of the black and white TV. The more realistic scenario is a To Do list with twenty items, each a mini-project in itself. That's what my life is usually like, so I use an outline processor. Each To Do task can be subdivided into subtasks. As tasks are accomplished, slide them down to a "Done" heading, probably further subdivided by date. This gives you a record of what you've done in case you need to do it again later on, or if you're an employee and have to account for your time.

The last 10 to 20 minutes before quitting time are devoted to updating tomorrow's To Do list. While this sounds like unproductive time, it saves triple itself or more. The next morning you pick up right where you left off.

Sometimes To Do list items become projects all to themselves. That's the time to move them off the To Do list and onto their own outline (probably merged with the parts of that project from the "Done" section). Then individual tasks from the project go on the To Do list.

And Much, Much More

The preceding examples just scratch the surface. A large percentage of human thought and action are organized hierarchically.  Anything in this world that's organized as a hierarchy is an instant candidate for an outline processor.
Steve Litt is the author of Troubleshooting Techniques of the Successful Technologist. He can be reached at Steve Litt's email address.

Try It, You'll Like It

By Steve Litt
The oddest thing is that few people use any kind of outlining in their lives, automated or otherwise. Outlines are taught sporadically in grade school and high school. In some school systems it's possible to go all the way through 12th grade without exposure to outlines. Even when they're taught, it's usually as an appendage to composition class. Few teachers add the single vital sentence: "and you can use it to plan absolutely anything".

If you don't use outlines, try them. Do it with pencil and paper if necessary. Or use a computer. Almost all word processing programs have at least a rudimentary outline processor. Use it for a To Do list, or to plan a weekend getaway. Use it to make a component list for the next computer you assemble. Use it to design your next computer program. Use it to brainstorm a Troubleshooting Mental Model.

If you want to double your productivity in planning or design, use an outliner. Once you start, you'll never stop.

Steve Litt is the author of Rapid Learning: Secret Weapon of the Successful Technologist. He can be reached at Steve Litt's email address.

Requirements of a Great Outline Processor

By Steve Litt
We all know outlines are an essential part of any planning or design process. The question is, what makes an outline processor great?

The top requirement is speed. The commonest operations must be doable from the touch typists home position. This includes promoting and demoting individual headlines, expanding and collapsing the current headline, and cursor movements. Cut and paste operations should be doable from the keyboard, and the amount actually copied or cut should be dependent on the extent a headline is expanded or collapsed. If a headline is expanded, cutting it should simply move that headline, leaving its subheads under the headline above it, or maybe there may be better ways to handle this situation. If the headline is collapsed, its entire tree is moved. There should be at least one level of undo.

A GUI move capability, while not essential, is a big plus that can save several seconds on move operations, and more importantly reduce the likelihood of error. It's nice if all indent/extend, expand/collapse, moving and copying can be done from the mouse. This lessens the necessity of repeatedly switching from keyboard to mouse.

An excellent outline processor prints in an easy to read manner. Reasonably consistent and intuitive indentation is a must. Configurable heading indicators (Roman numerals, letters, numeric dotted notation, etc.) is highly desirable. Custom fonts and spacing for different heading levels is nice.

An excellent outline processor must export its data to common formats such as popular word processors, HTML, or XML. Outstanding outline processors can bring the data back in from the common formats.

Grandview: The Orphan

A DOS outliner program called Grandview came out in the very early 90's. As a pure outliner, as opposed to an outliner/word processor, it had no peer. A heading copy could copy the entire tree, or it could copy the headline with a link back to the tree. Now THAT's a great software design tool. Better yet, it allowed you to have headings that were really links to other outlines. In 1994 I had almost my entire life in Grandview. So why don't I use it any more?

Symantec, the last known owner of Grandview, stopped selling and supporting it. If Grandview somehow stops working, all Grandview data becomes unreadable. Lost. That's just not a chance I can take. It sure would be nice to have Grandview for Linux. I issue this challenge to Symantec:

Make Grandview Open Source. It's been at least 5 years since you made a dime off it. From a Windows/GUI point of view it's completely obsolete. It runs on DOS, an obsolete OS. It's non-gui. Its data is stored in a proprietary format that will never again see the light of day. Grandview is now commercially worthless.

But it's an Open Source gold mine. The user interface, the front end, is 100% keyboard, and very keyboard independent. It can be used as is. It's probably easy to convert the display from DOS memory mapping to Linux curses. The keyboard access is trivial. Version 1 of Grandview for Linux can use the original Grandview file format. Soon after, version 2 can write to XML. Once that happens, there can easily be a Grandview for X.

Symantec -- do it. It's great PR and the Open Source community will love you.

I Use Microsoft Word (gulp)

Boy do I wish I could tell you I have a great GPL outline processor, but I don't. At the present time, MS Word (I use version 97 and will never upgrade) is just too good a product to replace. As mentioned, the commonest commands happen from the keyboard, all commands can be done from the mouse, and there's no switching between insert and outline mode. Up to nine heading styles make level customization a breeze, although the Word 97 product is much more quirky in that regard than were its Word 6 and Word 95 predecessors. But so far I haven't described anything that would place MS Word ahead of Corel Wordperfect, several Linux hosted word processors with built in outliners, or  even Netscape Composer.

The crucial difference, and one that's absolutely vital to anyone writing large documents, is that MS Word switches reversibly between outline and document view. Create the outline. Get it perfect. Then flip to document view, and every document heading becomes a part, a chapter, a heading, a subhead, etc. Nine levels deep. Fill in the sections with text. So far there's still nothing so great. But here's the fun part:

Flip it back to outline view, and you can manipulate your book or paper as an outline. You can view it as an outline, and instantly see the big picture. Move an entire chapter in seconds instead of minutes, and with much less chance of error or corruption than with other word processors. MS Word allows the author to continue making structural changes later in the document creation process than do other environments.

So if you write large documents, MS Word may be your best bet. Get an old box, install nothing but Windows 9x and MS Word, and network it to your Linux box via Samba. Do your Word work with Windows, and never upgrade. Sooner or later something out of the Open Source movement will be superior.

A Look to the Future

It seems obvious to me that the future of outline processing is XML. Here you have a configurable language that's meant to be displayed different ways. How tough can it be to make an XML DTD that defines headings and body text, and an app that hides or shows body text or hides or shows down to a certain level (complete with plus signs and minus signs)? Give the application real word processing capabilities, including the ability to embed graphics (either as simple pictures or as object links). Not easy, but certainly doable. Since XML is universal, such an app by its very nature can export and import from other XML enabled apps.

Perl and Python have XML interpreting capabilities. Hmmmmmm!

Steve Litt is the author of Troubleshooting Techniques of the Successful Technologist. He can be reached at Steve Litt's email address.

Linux Log: Outlining in Linux

Linux Log is now a regular column in Troubleshooting Professional Magazine, authored by Steve Litt. Each month we'll explore a facet of Linux as it relates to that month's theme.
Hot off the presses: 5/21/2001
High Quality Open Source Outliner for Linux
Vim version 6
Read about it here!
You can download the GPL VimOutliner Project

Troubleshooting Professional Magazine usually dispenses information. Today I'm asking for information. What outliner do you use in Linux?

I've been asking around. Some say lyx and klyx. Amaya is mentioned often. Wordperfect has an excellent outliner. It's unfortunate it doesn't (to my knowledge) have a toggle between outline view and document view. In Wordperfect, an outline is a subcomponent of a document. Wordprocessors from Star Office and Applix have outlining capability. Even Netscape Composer has limited outlining capability, though it lacks collapse/expand.

I'll bet somewhere there's an Open Source outliner, but wherever it is, it's not famous. It should be. I'll definitely join the project, as a coder or as a documenter. Do you know of a good outliner that runs on Linux? Email me.

Hot off the presses: 5/21/2001
High Quality Open Source Outliner for Linux
Vim version 6
Read about it here!
You can download the GPL VimOutliner Project
Steve Litt is the originator of the UMENU Software Project. He can be reached at Steve Litt's email address.

Letters to the Editor

All letters become the property of the publisher (Steve Litt), and may be edited for clarity or brevity. We especially welcome additions, clarifications, corrections or flames from vendors whose products have been reviewed in this magazine. We reserve the right to not publish letters we deem in bad taste (bad language, obscenity, hate, lewd, violence, etc.).
Submit letters to the editor to Steve Litt's email address, and be sure the subject reads "Letter to the Editor". We regret that we cannot return your letter, so please make a copy of it for future reference.

How to Submit an Article

We anticipate two to five articles per issue, with issues coming out monthly. We look for articles that pertain to the Troubleshooting Process. This can be done as an essay, with humor, with a case study, or some other literary device. A Troubleshooting poem would be nice. Submissions may mention a specific product, but must be useful without the purchase of that product. Content must greatly overpower advertising. Submissions should be between 250 and 2000 words long.

All submissions become the property of the publisher (Steve Litt), unless other arrangements are previously made in writing. We do not currently pay for articles. Troubleshooters.Com reserves the right to edit any submission for clarity or brevity. Any published article will include a two sentence description of the author, a hypertext link to his or her email, and a phone number if desired. Upon request, we will include a hypertext link, at the end of the magazine issue, to the author's website, providing that website meets the Troubleshooters.Com criteria for links and that the author's website first links to Troubleshooters.Com.

Submissions should be emailed to Steve Litt's email address, with subject line Article Submission. The first paragraph of your message should read as follows (unless other arrangements are previously made in writing):

I (your name), am submitting this article for possible publication in Troubleshooters.Com. I understand that this submission becomes the property of the publisher, Steve Litt, whether or not it is published, and that Steve Litt reserves the right to edit my submission for clarity or brevity. I certify that I wrote this submission and no part of it is owned by, written by or copyrighted by others.
After that paragraph, write the title, text of the article, and a two sentence description of the author.

URLs Mentioned in this Issue