Fabulous Adventures In Coding
Eric Lippert is a principal developer on the C# compiler team. Learn more about Eric.
No tech today. Too busy. But this was too precious to pass up:
The Greenlake neighbourhood in the north end of Seattle does something really cool; they have one weekend in April that everybody knows is "the garage sale weekend". Everyone who is going to have a spring garage sale has one on the same day, so the whole neighbourhood turns into one big sale. The stores have sidewalk sales, the community center sets up a market, the bakeries and coffee shops run charity and political fundraisers, everyone has a good time.
I occasionally make kites, but I've never had my own sewing machine; I've always had at least one housemate willing to let me use her sewing machine since I bought the house. But Chrissie moved to Ohio a couple weeks ago and took her sewing machine with her. Fortunately, on Garage Sale Day I managed to find a beautiful 1956 Kenmore Automatic Zig-zag Sewing Machine in great condition with all the original parts, manuals, bill of sale, a sewing machine table, bench, you name it, all for the low, low price of $45!
I haven't had a chance to set it up yet to see how it sews, but I read through the manual, which is hilarious. It begins like this:
At last you are the proud owner of an Automatic Zig Zag Sewing Machine. The machine was explained to you in detail, and you are now eagerly looking forward to the great variety of sewing techniques that can be performed on it.
Although everything is still quite clear to you, it is possible that in time some of the directions given to you for making the various adjustments may escape your memory -- because it is unlikely that you will immediately try your hand at all the different sewing techniques which your machine is capable of performing.
We have therefore prepared this informative book of instructions, and hope you will find it a useful guide.
(You love the second person voice. You find it calming. You trust and obey people who use the second person voice. You are getting very sleepy. Your eyelids are so heavy… )
It goes on like this for some time, explaining how to read a sewing machine manual in breathless, gushing, congratulatory, second-person prose. It even goes so far as to suggest that Chapter One would be a good thing to read next. Imagine if James Lipton wrote sewing machine manuals; that's what it's like.
I have seen worse. My mother has a cookbook written in 1972 which states "There are six basic ways to prepare eggs and it behooves a good wife to know all of them." Yes, behooves.
Technical writers, please, please start writing documentation like this.
You are deeply thrilled that, at long last, Microsoft has provided you with a built-in object-oriented XML-serialized security system in the .NET Framework. However, it behooves you to use it correctly. You may find that some of the signatures of certain seldom-used methods fade from memory, so we have provided you with this informative web page. You will find that more information on any underlined topic can be obtained by clicking the underlined word with your mouse...