An Approach to Reading Specifications Quickly

In this post, I'm going to give out one of my favorite secrets - how to read specifications quickly, with a high degree of retention. I have a particular technique, and if you use this technique, you may read specs more quickly, and you will remember more after you have read them.

 

This blog is inactive.
New blog: EricWhite.com/blog

Blog TOCPlease excuse the length of this posting - however, I'm going to bet that if you will take the 10 minutes or so that it will take to read it, you might save this time many times over the next time you sit down to read a specification.

 

A number of years ago, when I owned my small software business, one of our customers was a big defense contractor. We sold our products and services to a group that was working on a more complicated project. I became friends with one of the engineers there. He was one of those old-time engineers - wore pocket protectors - wrote in Fortran when he needed to write code, etc. Great guy. In one of our conversations, he told me about the voluminous specs for the project. They didn't measure the specs in thousands of pages; they measured it in hundreds of thousands of pages. They were using our custom control to write a program to manage all of these specs. And this engineer was familiar with a very big chunk of those specs. I'm such a nerd - he and I talked about specs for hours when we went out for a meal after work. Actually, if you want to find out how big of a nerd I am, just ask my wife :-)

 

Have you ever asked someone who has a PhD or MD about how much material they had to read in the process of getting their degree? One of my close friends is an MD. I watched her go through medical school, and saw the amount of material that she had to assimilate. It is cool to ask her about a particular disease. She has a nearly photographic memory, and she will more or less mentally open the book where she read about the disease, tell you that there are 12 symptoms, list them, and if the patient has seven or more, further tests are recommended. Of course, she doesn't count - she is brilliant, and it is unfair to compare the rest of us mere mortals with her intellectual capacity.

 

I think that the capacity of the human mind is marvelous.

 

I learned my spec reading technique by accident. It is a technique relatively new to me - I started using it only about 2 1/2 years ago, shortly after I started at Microsoft. The situation was this - I ride the bus to work every day, and have about a 45 minute ride, both morning and night. I wanted to make maximum use of this time, so I started reading technical books during my bus ride. However, my commute is broken up. I walk a few blocks, and then wait for 5-10 minutes for a bus. Then, I ride that bus for about 10 minutes. Then, I get off that bus, and wait for 5-10 minutes for another bus, which then takes about 20 minutes to get to the Microsoft campus. I kept finding that each time I had to look up from my book, get on or off the bus, etc., that I would lose my place on the page. So I started carrying pens along with my reading material. After reading (and comprehending) each sentence, I would put a slash through the period of the sentence. Then, when I next continued reading, it was simple to find my spot. I would start with the sentence after the last marked sentence. And of course, I would write editorial comments in the margins.

 

Well, the funniest thing happened. I felt like I was reading the technical material faster, and I was retaining more. So then, I started making different marks in the books, depending on the content of the sentence that I just read. If I read the sentence, and my mental response was simply, "got it", I would make my simple slash. If I read a sentence, and the assertion in the sentence was a more important one, I would write a sort of check mark - underline at the end of the sentence, and then an upwards slash. If I read the sentence, and I remembered that I had read this fact previously, but had forgotten it, I wrote a loop. And while reading a sentence, if there were lots of words in the sentence that were important to the meaning of the sentence, I would underline each important word. And I felt like my comprehension went up another notch.

 

It isn't that I go back and make use of these "hieroglyphics", as my friend Doug Mahugh, calls my marks. I think that my comprehension has gone up simply because I am bringing more consciousness to my technical reading.

 

Of course, I was destroying the book or printed spec, but my time is more important than a few dollars for a book, so I felt that ruining the book was a small price to pay for getting the material from the book or spec into my brain, while using my bus ride effectively. Then, for certain books, after reading the book, I would buy a clean copy for my bookshelf for future reference.

 

Of course, for reading specs, I would simply print out the specs, and use one of those staplers that can stable 50 pages together. After reading, I would just pitch it into the recycling bin.

 

I found that I could predict the rate at which I read books and specifications. Certain books were in the ~50 pages per hour range. Some books are in the ~75 pages per hour range. And some dense books on language or compiler theory are in the 20-25 pages per hour range. Whatever. With each type of material, my speed improved, and my comprehension improved.

 

Well, this brings us to the Open XML Specification, which is in the 75 pages per hour range. It is easy reading, for the most part. There are a few dense sections, but mostly it is material that a competent XML programmer can get through quickly. And there are lots of pictures, illustrations, examples, and non-normative text, which greatly improves the readability. I've had my job as technical evangelist for Open XML for four weeks, and I've already read a significant chunk of the spec. Of course, I tend to be task focused. For instance, I needed to help some developers who need to deal with change tracking, so I read the 150 pages or so that deal with annotations of all types. It took a couple of hours, pleasantly spent in a coffee shop with great south facing windows. (Necessary light therapy when in Seattle in January!)

 

There are three types of readers of the Open XML spec:

• Typical developers, who use the spec like a dictionary, or encyclopedia. They need to know the semantics of a particular element. They look it up, read it, and then proceed to writing code, or writing test cases, or what have you.
• Architects and system designers, who typically read more of the spec, but in less depth. These people are more concerned about acquiring an understanding of the basic semantic content of the spec as a whole, knowing that if in the future they need to get specifics on any particular element, they can go find it.
• Spec writers, including the editor of the spec, the subject matter experts who contribute to the spec, and the reviewers of the spec. These people have the greatest responsibility and are held to a higher standard. They need to make sure that the spec says what it should, and doesn't say what it shouldn't. This is (or should be) a self-selecting group. If someone doesn't have the capacity to read and assimilate material, then this isn't the group for them. But such a person shouldn't complain about the length of the spec. Leave the assessment of the length of the spec to the people competent to make that assessment.

 

I think that the complaints about the length of the dispositions are interesting. Most of the dispositions have a fair amount of "white space" in them, such as a table that repeats the comment originally made by the member body, the proposed change by the member body, a section listing similar comments by other member bodies, and the like. And every disposition is started on a new page, so the last page is nearly blank in many cases. The dispositions are more in the 100 page per hour range, for me. The length of the dispositions is simply a indication of the seriousness that the Ecma TC45 technical committee took the comments.

 

So from a common sense point of view, here is what I see:

 

The Open XML specification is a few thousand pages long. ISO ratification of this specification is important to the productivity of the entire world. Let's face it, there are a huge number of documents that are stored in a binary format that is convertible to Open XML with high fidelity. The passing of this specification means that developers and system designers will be able to rely on the format of documents. They will build innovative solutions (both open source and commercial) that will literally empower the productivity of the world for years to come.

 

In terms of spec size to benefits, this is a bargain.

Comments

• Anonymous
  January 28, 2008
  PingBack from http://msdnrss.thecoderblogs.com/2008/01/28/an-approach-to-reading-specifications-quickly/

• Anonymous
  January 30, 2008
  Open XML and XSLT with XMLSpy. Alex Falk has a great post on how to create a simple XSLT that transforms

• Anonymous
  January 30, 2008
  Open XML and XSLT with XMLSpy. Alex Falk has a great post on how to create a simple XSLT that transforms

• Anonymous
  February 03, 2008
  "ISO ratification of this specification is important to the productivity of the entire world" Exaggeration at its best. Up there with Salk and Einstein? "Leave the assessment of the length of the spec to the people competent to make that assessment." What is the length of the spec? Page count is a poor measure. Word count is slightly better, but not always indicative. A close approximation is the Zipped file size - how big is the Zipped spec?

• Anonymous
  February 03, 2008
  The comment has been removed

• Anonymous
  February 03, 2008
  How do a huge number of existing documents that can be converted from one format to another format bear on the importance of the -ratification- of a document that describes one of the formats? The existance of those documents is a drain on productivity, as they will either a) need time and effort to convert and to manage the conversion and to prevent documents from being re-converted (to avoid anomalies) , or b) require all future applications to maintain the conversion segment for each old format and to each newer one. Most of the huge number of documents are in the -other- format and the -other- format has no ratified ISO standard. Having the older formats ISO ratified would make a productivity boost, especially if it included a validation suite to ensure applications were generating valid files. 99.999999% of existing MS Binary-format files would have been better off being preserved as PDFs. The need to view and print existing documents far exceeds the need to edit them. Editting documents is often undesireable, such as for legal documents. Not all Microsoft bloggers know about WinZip or that the zip method used by MS Office 2007 is sub-optimal (~20% larger) WRT WinZip. I'm impressed.

• Anonymous
  February 03, 2008
  It started an email Mohamed Hossam (AKA, Bashmohandes) sent to my company's local office here in Egypt

• Anonymous
  February 04, 2008
  Dave S., In the Office Open XML Overview, in section 2, entitled, “Purposes for the Standard”, the first sentence says: “OpenXML was designed from the start to be capable of faithfully representing the pre-existing corpus of word-processing documents, presentations, and spreadsheets that are encoded in binary formats defined by Microsoft Corporation.” You may not agree with the stated purpose of the Ecma 376 standard, however Ecma’s standard is in alignment with its purpose. What we're trying to do here is to provide the most seamless way forward for all these people who have binary documents. Of course, IBM would rather force people to convert to ODF, and then sell consulting services to aleve their pain. With regards to the desirability of the binary formats over an XML format, I personally think that it is a no-brainer to allow developers to use any of the really good XML programming APIs, instead of munging around in a binary file. The CTO of ThinkFree (www.thinkfree.com) indicated that it was far easier to work with Open XML than the binary formats, and his company has done extensive work with both. I think that your assertion regarding binary format files would be better preserved as PDF is not correct. It certainly is not what we hear from our customers. And finally, regarding your comment about WinZip, sarcasm is not the most effective tool to convince people. I'd like to invite you to move the discussion up a level. Let's argue with supported assertions, politely phrased opinions, etc. :)

• Anonymous
  April 13, 2008
  The comment has been removed

• Anonymous
  April 23, 2008
  The comment has been removed