Troubleshooting Professional Magazine
|
Outlines: The Do Everything Tool |
|
High Quality Open Source Outliner for Linux Vim version 6 Read about it here! You can download the GPL VimOutliner Project |
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!
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Perl and Python have XML interpreting capabilities. Hmmmmmm!
|
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.
|
High Quality Open Source Outliner for Linux Vim version 6 Read about it here! You can download the GPL VimOutliner Project |
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):