The most important choice in writing is not what you say, it’s what you don’t say


"The most important choice in writing is not what you say. It's what you don't say." Eric Gunnerson gave me that advice when I was writing my book. It's sort of the writing version of "You don't know what you do until you know what you don't do."

That's why I'll write

Of course, you probably wonder this magical pfl comes from. It comes from the Multilanguage Object in mlang.

  IMLangFontLink2 *pfl;
  CoCreateInstance(CLSID_CMultiLanguage, NULL,
                   CLSCTX_ALL, IID_IMLangFontLink2, (void**)&pfl);
  ...
  pfl->Release();

and not

The pfl variable we've been using is an interface pointer to the IMLangFontLink2 interface. We obtain this pointer by calling the CoCreateInstance function, asking for the object whose class ID is CLSID_CMultiLanguage (defined in the mlang.h header file) and specifying the interface ID (IID) of IID_IMLangFontLink2. The interface ID is a 128-bit value that uniquely identifies an interface; we use it here to specify that we wish to have access to the IMLangFontLink2 interface. Since COM uses explicit reference counting, we must remember to call the IUnknown::Release method when we are finished with the interface pointer. Each call to the IUnknown::Release method decrements the reference count by one, and when the reference count drops to zero, the object is destroyed.

  IMLangFontLink2 *pfl;
  CoCreateInstance(CLSID_CMultiLanguage, NULL,
                   CLSCTX_ALL, IID_IMLangFontLink2, (void**)&pfl);
  ...
  pfl->Release();

This is why I hate reading technical books. People think it's better to write fifty words when ten are enough, that you should explain everything in excruciatingly tedious detail just in case there's a reader out there who sees the word CoCreateInstance and says, "Gosh, I don't know what that is, and I'm going to declare this book useless unless it explains everything from first principles."

What next? "The left open brace begins a block of statements"?

Comments (34)
  1. BobD says:

    yes!  …and by extension, using a $5 word when a plain 5c word will do just as well.  (but sometimes an uncommon word is good for variety too)

  2. Rob H says:

    I completely agree. So much time is spent describing every insignificant detail that the big picture, the important ideas, are either left out entirely or buried so they’re impossible to find. Exam preparation books are the worst offenders.

    Technical documentation is often frustrating in a similar way. There’s rarely an explanation of how the system works–instead, the function of each button and menu option is meaninglessly enumerated.

  3. richard says:

    I absolutely concur. Books are too bloated for my taste. I want to get to the meat of the matter, not wade through 75 pages, only to find I am given a cursory overview. This is why I hate fat books.

    I tihnk more authors should take Lister Sinclair’s (of Ideas fame on CBC radio) philosophy, "I always assume that my listeners are intelligent and knowledgeable in every subject, except the one I am presenting."

  4. David Walker says:

    BUT: Sometimes Help files, in particular, are not that helpful.

    The context help for things like Internet Explorer advanced options and for Security settings custom levels, basically says "select the option that you want".  Before the days of Google, it was sometimes un-possible to find out what each option actually MEANT, or when you would want to use them.

    Writing documentation at the right level is hard.

  5. George Jansen says:

    I have seen cited the following passage from William James’s Principles of Psychology, ch. 22:

    But we need not go as far as the ways of genius. Ordinary social intercourse will do. There the charm of conversation is in direct proportion to the possibility of abridgment and elision, and in inverse ratio to the need of explicit statement. With old friends a word stands for a whole story or set of opinions. With new-comers everything must be gone over in detail. Some persons have a real mania for completeness, they must express every step. They are the most intolerable of companions, and although their mental energy may in its way be great, they always strike us as weak and second-rate.

  6. J. Edward Sanchez says:

    "I apologize that this letter is so long. I did not have the time to make it short."

    Attribution: http://www.classy.dk/log/archive/001074.html

  7. Brian says:

    This is what is so great about hypertext.  If you don’t know what mlang is, you click it.  If you don’t know what CoCreateInstance does, you click it.  This is also why I have abandoned dead trees for technical information.

  8. Antoine de Saint-Exupéry says:

    "Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away."

  9. Mr Cranky says:

    You are correct — but conversely there are people who just skim over your finely crafted writing and so misunderstand it completely.

  10. Mikkin says:

    I also detest most technical writing for this reason. As an editor wisely told me:  If you can’t make the point succinctly then you have not mastered the subject.

  11. MS says:

    The important thing, I think, is that the targeted audience is already going to know how to use COM.  If I didn’t and read the former sample, I’d be just as frustrated as if I did know and read the second sample.  Of course, learning COM is a subject that probably should be handled away from practical code like I’m assuming was being discussed.

    [If you don’t know COM, you shouldn’t be reading this blog. That’s one of the implicit prerequisites. -Raymond]
  12. BradC says:

    [If you don’t know COM, you shouldn’t be reading this blog. That’s one of the implicit prerequisites. -Raymond]

    I bet you’d be surprised–I obviously don’t have any hard data, but I would guess that a pretty small percentage of your regular daily audience knows COM.

    I don’t. I’m a .Net developer that enjoys your stories, your anecdotes and advice about development.

    The highly-technical posts? I skip past them or browse them quickly to see if there are any amusing "nitpicker’s corner" comments :)

  13. BradC says:

    Point of clarification: I obviously KNOW I am not the target audience for your above discussion on "pfl mlang", so I don’t spend any real time worrying about it.

    So I’m obviously going to post any daft questions that reveal my ignorance of COM.

  14. I suspect the target audience and subject material play an important role in how much detail should be given, and most decent authors are acutely aware of this.  So I don’t think you’ve established any general rule of thumb here; you have established that blatant digression is a bad thing.  It’s a bit of a straw man, though, because your example digresses to a ridiculous degree.  I’ve never seen published writing in a technical book that’s so obviously off-topic, and if I did, I’d ask for my money back.

    That said, the opposite can be equally infuriating: technical writers who expect readers to infer vast amounts of information based on scanty sentences and examples.  Or writers who assume their readers have a level of technical expertise that’s much higher than they do in reality.

    [This “straw man” was actual feedback from a draft copy of my book. I chose to ignore it. -Raymond]
  15. Adrian says:

    I know a little COM, but don’t have much experience with it.  Nevertheless, I’ve gotten lots out of your blog over the years.

    I know many long-term (10+ year) WinAPI developers who’ve never touched COM.  Sure, some of your posts are specific to COM, but there’s lots of good stuff in there for the rest of us, too.

    It always surprises me when people assume Win32 and COM are tightly coupled.

    [If some articles make sense without knowledge of COM then lucky you, but I will still assume you know it. -Raymond]
  16. Triangle says:

    Dear God, it’s exactly like reading the Intel manuals. (Except they use pictures instead of code samples).

  17. Nugae says:

    People don’t realise that computing isn’t technology, it’s literature. A program is nothing but a literary work with a side-effect: the side-effect is that the literary work can be compiled and executed.

  18. poochner says:

    I’ve seen examples as bad as Raymond showed in the post.  They’re frightening–even more when they come off your own pen.  At some point, you have to sit back and look at what you’re doing and say, "that’s just too complicated. I must be doing it wrong!" and toss it and start over.  You’ll have a better understanding of what you wanted to accomplished.

    At least when we see big code examples here, they’re from a known sample program and the changes are highlighted.

    I’ve always said computing is just applied math.  Computer science isn’t all that applied, either.

  19. MM says:

    This is the reason I *HATE* all those webcasts and tech videos around. With paper, at least you can "autodetect" the sugar you don’t care about and go straight to the facts. You can’t do that in a video.

  20. Sitten Spynne says:

    As has already been stated, the amount of detail required really has to do with the target audience.

    Even though I’d agree that many of your readers aren’t really COM programmers (I’m not, and have never really touched COM), there’s no need to for you to assume they aren’t.  I’ve always viewed this blog as a great resource for two things: nasty hard-to-understand pitfalls of COM (which I don’t need) and humorous accounts of people doing stupid things (which I do need).

    When I see a COM post I often don’t understand what you are talking about but since I’m not coming here for a COM reference it doesn’t really bother me.

  21. Dan McCarty says:

    "If you don’t know COM, you shouldn’t be reading this blog. That’s one of the implicit prerequisites."

    implicit as in "negligible," maybe.

    The COM posts are few and far between.  Of the last 15 posts that make up the "front page," none is a COM post.  (1 if you count this one.)

    I’ve been reading this blog for several years and never knew I should’ve gone and learned COM.  I guess I should go away now.

  22. MikeC says:

    I don’t know COM, but most (over 90% of read) of the articles here have still been informative / useful / entertaining. Enough so, that I make it a point to come here for 5-10 mins every day at 3pm (UK BST), no matter what else is outstanding at that time.

    Even if an article is about COM – a lot of the time, some coding principles can still be taken away and applied in other areas (VB and derivatives for me).

    If it’s not about COM, it’s usually interesting and / or entertaining, and even as a non-COM dev, I can say "Oh gods, I SO relate!!" on ones like the "if you don’t like the answer, ask smarter questions" e-mails! =:-)

  23. Damian says:

    Actually this is a reason why books kinda suck. Imagine if the source in your book could be hyperlinked like this: http://www.koders.com/cpp/fid063AA08AB8E368E2165204A0A4E5F4EDF9585183.aspx?s=CoCreateInstance

    Of course desktops and even laptops are sucky for reading long passages of text. Somewhere in the future there will be an ebook reader / umpc / tablet that will hit that sweet spot.

  24. Jules says:

    [This "straw man" was actual feedback from a draft copy of my book. I chose to ignore it. -Raymond]

    I’ve heard it said that the difference between a poor writer and a good one is that the good one knows which advice to ignore.

  25. KC says:

    This ancedote brings back memories of my days debugging MFC apps.  It seemed that, more often than not, the fix to a bug was to remove code you wrote that was getting in the way.

     KC

  26. Andy Cowenhoven says:

    I think the most important choice is in deciding what terminology you must define for your reader and what terms you can assume they already understand.

  27. I get what you’re saying, but even specifying a book’s target audience wouldn’t satisfy everyone.  I agree what several people have said — hyperlinked (and up-to-date) material is a much better solution for these types of books (but no underlines for the links in these types of articles, and no annoying bubbles, please — there are much cleaner ways to create the UI for this).  And one day the tools will approach the easability of books.

    The bigger issue that I have with most technical books is that they spend way too much on teaching the "what" details, and way too little on teaching the "why".

  28. MS says:

    "[If you don’t know COM, you shouldn’t be reading this blog. That’s one of the implicit prerequisites. -Raymond]"

    Oh, I know COM well enough, and I didn’t mean to imply otherwise.  Andy Cowenhoven makes a similar point to the one I was trying to make — you knew your target audience was most likely to know COM, so the former sample is best.

  29. Miral says:

    I know enough about COM to get by, but I generally treat it with distrust and disdain and avoid it wherever possible.  (The same is true of things like Mozilla’s XPCOM.  I don’t discriminate.)

    It’s the sort of thing that I’ll touch if I have to, but I’ll wash my hands afterwards :)

  30. Gene says:

    Strunk & White’s classic manual "The Elements of Style" makes "Omit needless words!" a major point.

    I firmly believe the brevity of "Kernigan & Ritchie" is a major reason why C was so quickly adopted by the world and became such a standard. People could quickly and easily understand the language enough to start programming in it in maybe a week, max.

  31. fschwiet says:

    What was it Shakespeare said?  Brevity is wit?

  32. fschwiet says:

    What was it Shakespeare said?  Brevity is wit?

  33. Bogus says:

    Raymond, you’ve got really great blog here and I make it a point to read it regularly. But I only know basic Win32 and absolutely no COM. I have a vague idea that CoCreateInstance is some kinda constructor call, and that if you mess up your reference counts, you will leak, but that is the limit of my knowledge. And you know what? I don’t need to know COM either, my job involves writing signal processing and analysis code mostly in C++, and sometimes in assembly language. I still think there is a lot of value in reading this blog. All that stuff about how MS preserved compatibility was fascinating. I also lapped up all the DLL related stuff, because I build DLLs that other people use. And I learned a lot about how software grows and becomes more and more of a mess to maintain, and how experienced developers tame the beast.

    Much as I appreciate most of your content, I fail to see any great insights in either this post or your subsequent comments.

Comments are closed.