Coding Horror

programming and human factors

How to Write Technical Documentation

I was browsing around the CouchDb wiki yesterday when I saw Damien Katz' hilarious description of how technical documentation really gets written. You know, in the real world:

Welcome to the world of technical documentation!

The situation you are in is no different from any other tech writer. The technical writing process:

  1. Ask engineer how the damn thing works.
  2. Deafing silence.
  3. Crickets.
  4. Tumbleweed.
  5. Just start writing something. Anything.
  6. Give this something to the engineer.
  7. Watch engineer become quite upset at how badly you've missed the point of everything.
  8. As the engineer berates you, in between insults he will also throw off nuggets of technical information.
  9. Collect these nuggets, as they are the only reliable technical information you will receive.
  10. Try like hell to weave together this information into something enlightening and technically accurate.
  11. Go to step 6.

Ok, you're not the doc writing type. That's okay, neither am I. However, people are already working to make this better, and I will continue to do so.

I think I've been on both ends of this exchange at some point in my career. It's funny because it's true. I'm sure I've read descriptions exactly like this on Mike Pope's blog.

Discussion

The Programmer's Bill of Rights

It's unbelievable to me that a company would pay a developer $60—$100k in salary, yet cripple them with terrible working conditions and crusty hand-me-down hardware. This makes no business sense whatsoever. And yet I see it all the time. It's shocking how many companies still don't provide software developers with the essential things they need to succeed.

I propose we adopt a Programmer's Bill of Rights, protecting the rights of programmers by preventing companies from denying them the fundamentals they need to be successful.

The Bill of Rights
  • Every programmer shall have two monitors

    With the crashing prices of LCDs and the ubiquity of dual-output video cards, you'd be crazy to limit your developers to a single screen. The productivity benefits of doubling your desktop are well documented by now. If you want to maximize developer productivity, make sure each developer has two monitors. Or three.

  • Every programmer shall have a fast PC

    Developers are required to run a lot of software to get their jobs done: development environments, database engines, web servers, virtual machines, and so forth. Running all this software requires a fast PC with lots of memory. The faster a developer's PC is, the faster they can cycle through debug and compile cycles. You'd be foolish to pay the extortionist prices for the extreme top of the current performance heap – but always make sure you're buying near the top end. Outfit your developers with fast PCs that have lots of memory. Time spent staring at a progress bar is wasted time.

  • Every programmer shall have their choice of mouse and keyboard

    In college, I ran a painting business. Every painter I hired had to buy their own brushes. This was one of the first things I learned. Throwing a standard brush at new painters didn't work. The "company" brushes were quickly neglected and degenerated into a state of disrepair. But painters who bought their own brushes took care of them. Painters who bought their own brushes learned to appreciate the difference between the professional $20 brush they owned and cheap disposable dollar store brushes. Having their own brush engendered a sense of enduring responsibility and craftsmanship. Programmers should have the same relationship with their mouse and keyboard – they are the essential, workaday tools we use to practice our craft and should be treated as such.

  • Every programmer shall have a comfortable chair

    Let's face it. We make our livings largely by sitting on our butts for 8 hours a day. Why not spend that 8 hours in a comfortable, well-designed chair? Give developers chairs that make sitting for 8 hours not just tolerable, but enjoyable. Sure, you hire developers primarily for their giant brains, but don't forget your developers' other assets.

  • Every programmer shall have a fast internet connection

    Good programmers never write what they can steal. And the internet is the best conduit for stolen material ever invented. I'm all for books, but it's hard to imagine getting any work done without fast, responsive internet searches at my fingertips.

  • Every programmer shall have quiet working conditions

    Programming requires focused mental concentration. Programmers cannot work effectively in an interrupt-driven environment. Make sure your working environment protects your programmers' flow state, otherwise they'll waste most of their time bouncing back and forth between distractions.

The few basic rights we're asking for are easy. They aren't extravagant demands. They're fundamental to the quality of work life for a software developer. If the company you work for isn't getting it right, making it right is neither expensive nor difficult. Demand your rights as a programmer! And remember: you can either change your company, or you can change your company.

Discussion

Coding Horror Sightings

The free stickers were all mailed Monday. Here's a quick statistical breakdown, courtesy of my wife:

United States320
Canada49

38 of the 50 states were represented. The states with zero sticker requests were: HI, KS, LA, MS, MT, ND, NM, RI, SD, VT, WV and WY. Here are the top 10 states:

CA32
TX26
WA16
FL16
PA13
MA13
CO13
IL13
OH12
MN12

And here's a similar breakdown for Canadian provinces:

Ontario15
Alberta11
Quebec10
British Columbia9
New Brunswick1
Manitoba1
Nova Scotia1
Saskatchewan1

Contrary to popular belief, I am fully aware that the United States isn't the only country in the world. Here's a breakdown of the international orders to date:

United Kingdom7
Australia3
Germany2
Finland1
Brazil1
Switzerland1
Sweden2
Belgium1
Denmark1
New Zealand1
Latvia1

Although the free sticker offer is over, you can still buy a set of 4 stickers for $3. They're usually mailed the same day.

Will Sullivan's is appropriately positioned next to a real coding horror. Bryan Likes created the infinite cat project recursive version.
codinghorror-sighting-sullivan.jpg codinghorror-sighting-likes.jpg
Here's one from my fellow developers at Vertigo. If you work with me, I'll give you a sticker. But only grudgingly. Sam Livingston-Gray put his to good use covering up that hideous Apple logo. Bonus points for real-life simulation!
codinghorror-sighting-vertigo.jpg codinghorror-sighting-livingston2.jpg
Matt Blodgett evidently doesn't own a digital camera. But he does have mad MS Paint skills. My old friend Geoff Dalgas created this animated version of the sticker.
codinghorror-sighting-blodgett.png codinghorror-animated.gif
Brian Stephens works on Titan Quest, which doesn't play like a Coding Horror. Bryan Kramer sighted his at a Jacksonville, Florida Code Camp during a marathon not-for-profit coding session.
codinghorror-sighting-stephens.jpg codinghorror-sighting-kramer.jpg
David Howell gave his sticker a place of honor in his cube. Nathan Birkes used his sticker to pimp out his Grand Prix. Stylin'!
codinghorror-sighting-howell.JPG codinghorror-sighting-birkes.jpg
Steve Makofsky works at Microsoft. Guess what part of Vista he worked on? Martin Marconcini is going for sticker symmetry on his Ford Focus.
codinghorror-sighting-makofsky.jpg codinghorror-sighting-marconcini.jpg

If you have any Coding Horror sticker or T-shirt "action shots", email them to me, and I'll post them here.

Discussion

Building a Quiet PC

When the first version of Windows Media Center was released in summer 2003, I decided it was time to build my first home theater PC. After I placed it in the living room, I realized I had made a terrible mistake: I had to turn the volume up to 11 just to drown out the noise of the HTPC! I couldn't believe how loud it was! For the next few months, I immersed myself in the world of silent PC enthusiasts. I must have reconfigured that system a dozen times to reduce the noise.

Now every PC I build is optimized for performance and low noise from the very beginning.

Anyone can build a high-powered rig that sounds like a jet taking off. Building a high-powered rig that's so quiet your wife can't tell when it's turned on or off-- now that's an accomplishment! It's a bona-fide engineering challenge.

In the process, I've learned quite a few things about building quiet PCs. I'd like to share them with you, so you can avoid making the mistakes I did.

  1. The easiest way to build a quiet PC is to start with components that run cool. It's as fundamental as the first law of thermodynamics: heat has to be exhausted from the system; more heat equals more noise. If you truly want a quiet system, start with cool running components. The three components that generate the most heat in your system are..

    1. CPU
    2. video card
    3. power supply

    .. in that order. Select these items very carefully, because they will account for 90 percent of the heat and noise generated inside your computer. Research how many watts of power each will draw when idle; when normally loaded; and when fully loaded.

    And don't underestimate the importance of the power supply; it's the heart of your system, and it can be the source of serious stability, noise, and heat woes if you pick a clunker. The very best power supplies are only about 85% efficient, which means they're still dumping 15% of the total power draw back into your case as waste heat.

  2. Minimize the number of fans in your system. Every fan is a source of noise. Remove fans unless they're absolutely necessary. If a fan is necessary, use the largest possible model. All other things being equal, large fans are quieter than small fans. That's why 120mm fans are now commonplace in PC cases.

    One of the most useful noise diagnostics is to stop every fan in the system, one by one, using your Mark I finger. Repeat this a few times, listening closely to hear the difference with each fan stopped. Then try to eliminate or slow down the noisiest fan. Don't forget to test your video cards and motherboard fans while you're at it; these tend to be particularly noisy due to their small size. And remember, kids, always stop fans by touching them in the center, not in those whirling blades!

  3. Control the speed of your fans. Fans running at full speed are almost never quiet. Some modern motherboards allow you to control the speed of the fans connected via the 3-pin motherboard headers, either in the BIOS or in software. Set an absolute speed, or even better, use dynamic fan speeds based on a temperature sensor; spin faster when it gets hot, and slow down when things cool off. There are also devices like the Zalman Fanmate that allow you to retrofit a fan speed control on any 3-pin fan.

    Zalman FanMate

    The Zalman 56 Ohm resistor is a less expensive option if you don't need precise speed control.

  4. Consider aftermarket cooling solutions. Aftermarket coolers for CPUs and video cards are typically far more efficient than the stock models manufacturers include. You might be able to get away with inefficient stock coolers for basic systems, but if you want high-end performance, a super-efficient cooler can literally be the difference between a quiet system and a loud system.

    scythe ninja CPU cooler  accelero-x1 video/GPU cooler  Zalman NB47 northbridge cooler

    Note that aftermarket coolers tend to be quite a bit larger than stock coolers; measure to make sure they'll fit in your system before buying.

  5. Dampen your hard drive. Hard drive manufacturers have made huge strides in noise reduction in the last few years. You still need to be a bit careful in selecting a drive, but most new hard drives are relatively quiet. That's the good news. The bad news is that hard drives are still giant hunks of metal spinning at 7,200 or 10,000 RPM.

    As such, the first order of business here is to dampen the drives -- make absolutely sure there is a soft material of some kind between the hard drive and your PC's case. Some people improvise bungee suspension slings, some people use foam or sorbothane, some people put them in dampening enclosures. Whatever you do, always avoid metal-to-metal contact between a hard drive and the case.

    hard drive bungee suspension frame

    The truly hardcore use 2.5" laptop hard drives, which are even quieter, but they also have significant performance and price penalties over standard 3.5" desktop drives.

  6. Use noise-reduction materials. If you've ever worked in a recording studio where the walls are covered with noise-reduction materials, you've probably heard first-hand how effective they can be. However, noise reduction materials are strictly a second line of defense. They treat the symptom and not the source; ideally you want to quiet the thing that is making noise-- not hide it behind a layer of dampening material.

    That said, noise reduction materials can help take the edge off the last remaining bit of noise in a system. For PC builds, I like pax.mate and generic eggcrate foam. You can see pictures of both materials in action in this SilentPCReview thread documenting a LAN party system I built in summer 2004. But they should always be a final, finishing step.

    eggcrate foam for acoustic damping

    I'm ashamed to admit that I have something of an eggcrate foam fetish. In addition to wedging it inside my systems wherever it'll fit, I regularly put cardboard-mounted panels of the eggcrate foam behind my PCs to reduce the reflected noise from the rear exhaust fans. If your PC is under a desk, fitting eggcrate foam along the undersides of the desk can be surprisingly effective, too.

  7. Passive cooling isn't worth it. If you really get bitten by the silence bug, you'll invariably be drawn to that holy grail of silent computing: completely passive cooling. Passive cooling is totally silent by definition, but also it's the equivalent of scaling the Himalayas-- not something you undertake lightly and certainly not without a few years of experience under your belt.

    Although there are exotic pre-built passive solutions like Zalman's TNN-500A and TNN-300 cases, they're solidly in the "if you have to ask how much it costs, you can't afford it" category.

    Zalman TNN 500a fanless computer case

    Passive cooling setups are an order of magnitude more difficult to cool: they require a tricky balance of careful construction, natural convective airflow, and setup tweaking. You can achieve 90 percent of the results you'd get with completely passive cooling using a few nearly-silent, slow-moving fans-- at a fraction of the effort and risk!

I can't emphasize enough that the best way to quiet your PC is to begin with the right parts. If you're really serious about silence, ensure that you have..

  • CPUs and video cards that run cool
  • a quiet, efficient power supply
  • hard drives that run relatively quiet as shipped

Always try to deal with the source of the noise first. Beyond that, following the few tips I outlined above will eventually get you to near-complete silence-- or at least to below-ambient noise level, which is pretty much the same thing.

Discussion