Jul 14

Documentation as knowledge capture

Maybe you’re one of the tiny minority of programmers that, like me, already enjoys writing documentation and works hard at doing it right. If so,the rest of this essay is not for you and you can skip it.

Otherwise, you might want to re-read (or at least re-skim) Ground-Truth Documents before continuing. Because ground-truth documents are a special case of a more general reason why you might want to try to change your mindset about documentation.

In that earlier essay I used the term “knowledge capture” in passing. This is a term of art from AI; it refers to the process of extracting domain knowledge from the heads of human experts into a form that can be expressed as an algorithm executable by the literalistic logic of a computer.

What I invite you to think about now is how writing documentation for software you are working on can save you pain and effort by (a) capturing knowledge you have but don’t know you have, and (b) eliciting knowledge that you have not yet developed.

Humans, including me and you, are sloppy and analogical thinkers who tend to solve problems by pattern-matching against noisy data first and checking our intuitions with logic after the fact (if we actually get that far). There’s no point in protesting that it shouldn’t be that way, that we should use rigorous logic all the way down, because our brains simply aren’t wired for that. Evolved cognition is a kludge – more properly, multiple stacks of kludges – developed under selection to be just barely adequate at coping.

This kludginess is revealed by, for example, optical illusions. And by the famous 7±2 result about the very limited sized of the human working set. And the various well-documented ways that human beings are extremely bad at statistical reasoning. And in many other ways…

When you do work that is as demanding of rigor as software engineering, one of your central challenges is hacking around the limitations of your own brain. Sometimes this develops in very obvious ways; the increasing systematization of testing during development during the last couple of decades, for example.

Other brain hacks are more subtle. Which is why I am here to suggest that you try to stop thinking of documentation as a chore you do for others, and instead think of it as a way to explore your problem space. and the space in your head around your intuitions about the problem, so you can shine light into the murkier corners of both. Writing documentation can function as valuable knowledge capture about your problem domain even when you are the only expert about what you are trying to do.

This is why my projects often have a file called “designer’s notes” or “hacking guide”. Early in a project these may just be random jottings that are an aid to my own memory about why things are the way they are. They tend to develop into a technical briefing about the code internals for future contributors. This is a good habit to form if you want to have future contributors!

But even though the developed version of a “designer’s notes” looks other-directed, it’s really a thing I do to reduce my own friction costs. And not just in the communication-to-my-future-self way either. Yes, it’s tremendously valuable to have a document that, months or years after I wrote it, reminds me of my assumptions when I have half-forgotten them. And yes, a “designer’s notes” file is good practice for that reason alone. But its utility does not even start there, let alone end there.

Earlier, I wrote of (a) capturing knowledge you have but don’t know you have, and (b) eliciting knowledge that you have not yet developed. The process of writing your designer’s notes can be powerful and catalytic that way even if they’re never communicated. The thing you have to do in your brain to narratize your thoughts so they can be written down is itself an exploratory tool.

As with “designer’s notes” so with every other form of documentation from the one-line code comment to a user-oriented HOWTO. When you achieve right mindset about these they are no longer burdens; instead they become an integral part of your creative process, enabling you to design better and write better code with less total effort.

I understand that to a lot of programmers who now experience writing prose as difficult work this might seem like impossible advice. But I think there is a way from where you are to right mindset. That way is to let go of the desire for perfection in your prose, at least early on. Sentence fragments are OK. Misspellings are OK. Anything you write that explores the space is OK, no matter how barbarous it would look to your third-grade grammar teacher or the language pedants out there (including me).

It is more important to do the discovery process implied by writing down your ideas than it is for the result to look polished. If you hold on to that thought, get in the habit of this kind of knowledge capture, and start benefiting from it, then you might find that over time your standards rise and it gets easier to put more effort into polishing.

If that happens, sure; let it happen – but it’s not strictly necessary. The only thing that is necessary is that you occasionally police what you’ve recorded so it doesn’t drift into reporting something the software no longer does. That sort of thing is a land-mine for anyone else who might read your notes and very bad form.

Other than that, though, the way to get to where you do the documentation-as-knowledge-capture thing well is by starting small; allow a low bar for polish and completeness and grow the capability organically. You will know you have won when it starts being fun.

Jul 06

How not to treat a customer

First, my complaint to Simply NUC about the recent comedy of errors around my attempt to order a replacement fan for Cathy’s NUC. Sorry, I was not able to beat WordPress’s new editor into displaying URLs literally, and I have no idea why the last one turns into a Kindle link.


Subject: An unfortunate series of events

Simply NUC claims to be a one-stop shop for NUC needs and a customer-centric company. I would very much like to do business with an outfit that lives up to Simply NUC’s claims for itself. This email is how about I observed it to fail on both levels.

A little over a week ago my wife’s NUC – which is her desktop machine, having replaced a conventional tower system in 2018 – developed a serious case of bearing whine. Since 1981 I have built, tinkered with, and deployed more PCs than I can remember, so I knew this probably meant the NUC’s fan bearings were becoming worn and could pack up at any moment.

Shipping the machine out for service was unappealing, partly for cost reasons but mostly because my wife does paying work on it and can’t afford to have it out of service for an unpredictable amount of time. So I went shopping for a replacement fan.

The search “NUC fan replacement” took me here:

NUC Replacement Fans

There was a sentence that said “As of right now SimplyNUC offers
replacement fans for all NUC models.” Chasing the embedded link
landed me on the Simply NUC site here:

Nuc Accessories

Now bear in mind that I had not disassembled my wife’s NUC yet, that I had landed from a link that said “replacement fans for all NUC models”, and that I didn’t know different NUCs used different fan sizes.

The first problem I had was that this page did nothing to even hint that the one fan pictured might not be a universal fit. Dominic has told me over the phone that “Dawson” is a NUC type, and if I had known that I might have interpreted the caption as “fit only for Dawsons”. But I didn’t, and the caption “Dawson BAPA0508R5U fan” looks exactly as though “Dawson” is the *fan vendor*.

So I placed the order, muttering to myself because there aren’t any shipping options less expensive than FedEx.

A properly informative page would have labeled the fan with its product code and had text below that said “Compatible with Dawson Canyon NUCs.” That way, customers landing there could get a clue that the BAPA0508R5U is not a universal replacement for all NUC fans.

A page in conformance with Simply NUC’s stated mission to be a one-stop NUC shop would also carry purchase links to other fans fitted for different model ranges, like the Delta BSC0805HA I found out later is required for my wife’s NUC8i3BEH1.

The uninformative website page was strike one.

In the event, when the fan arrived, I disassembled my wife’s NUC and instantly discovered that (a) it wasn’t even remotely the right size, and (b) it didn’t even match the fan in the website picture! What I was shipped was not a BAPA0508R5U, it’s a BAAA0508RSH.

Not getting the product I ordered was strike two.

I got on the Simply NUC website’s Zendesk chat and talked with a person named Bobbie who seemed to want to be helpful (I point this out because, until I spoke with Dominic, this was the one single occasion on which Simply NUC behaved like it might be run by competent people). I ended up emailing her a side-by-side photo of the two fans. It’s attached.

Bobbie handed me off to one Sean McClure, and that is when my experience turned from bad to terrible. If I were a small-minded person I would be suggesting that you fire Mr. McClure. But I’m not; I think the actual fault here is that nobody has ever explained to this man what his actual job is, nor trained him properly in how to do it.

And that is his *management’s* fault. Somebody – possibly one of the addressees of this note – failed him.

Back during the dot-com boom I was on the board of directors of a Silly Valley startup that sold PCs to run Linux, competing directly with Sun Microsystems. So I *do* in fact know what Sean McClure’s job is. It’s to *retain customers*. It’s to not alienate possible future revenue streams.

When a properly trained support representative reads a story like mine, the first words he types ought to be something equivalent to “I’m terribly sorry, we clearly screwed up, let me set up an RMA for that.” Then we could discuss how Simply NUC can serve my actual requirements.

That is how you recruit a loyal customer who will do repeat business and recommend you to his peers. That is how you live up to the language on the “About” page of your website.

Here’s what happened instead:

Unfortunately we don’t keep those fans in stock. You can try reaching out to Intel directly to see if they have a replacement or if they will need to RMA your device. You can submit warranty requests to: supporttickets.intel.com, a login will need to be created in order to submit the warranty request. Fans can also be sourced online but will require personal research.

This is not an answer, it’s a defensive crouch that says “We don’t care, and we don’t want your future business”. Let me enumerate the ways it is wrong, in case you two are so close to the problem that you don’t see it.

1. 99% odds that a customer with a specific requirement for a replacement part is calling you because he does *not* want to RMA the entire device and have it out of service for an unpredictable amount of time. A support tech that doesn’t understand this has not been taught to identify with a customer in distress.

2. A support tech that understands his real job – customer retention – will move heaven and earth rather than refer the customer to a competing vendor. Even if the order was only for a $15 fan, because the customer might be experimenting to see if the company is a competent outfit to handle bigger orders. As I was; you were never going to get 1,000 orders for whole NUCs from me but more than one was certainly possible. And I have a lot of friends.

3. “Personal research”? That’s the phrase that really made me angry. If it’s not Simply NUC’s job to know how to source parts for NUCs, so that I the customer don’t have to know that, what *is* the company’s value proposition?

Matters were not improved when I discovered that typing BAPA0508R5U into a search engine instanntly turned up several sources for the fan I need, including this Amazon page:

A support tech who understood his actual job would have done that search the instant he had IDed the fan from the image I sent him, and replied approximately like this: “We don’t currently stock that fan; I’ll ask our product guys to fix this and it should show on our Fans page in <a reasonable period>. In the meantime, I found it on Amazon; here’s the link.” >

As it is, “personal research” was strike three.

Oh, and my return query about whether I could get a refund wasn’t even refused. It wasn’t even answered.

My first reaction to this sequence of blunders was to leave a scathingly bad review of Simply NUC on TrustPilot. My second reaction was to think that, in fairness, the company deserves a full account of the blunders directed at somebody with the authority to fix what is broken.

Your move.


Here’s the reply I got:


Mr. Raymond, while I always welcome customer feedback and analyze it for
opportunities to improve our operations, I will not entertain customers who
verbally berate, belittle, or otherwise use profanity directed at my
employees or our company. That is a more important core value of our
company than the pursuit of revenue of any size.

I’ve instructed Sean to cancel the return shipping label as we’ve used enough of each other’s time in this transaction. You may retain the blower if it can be of any use to you or one of your friends in the future, or dispose of it in an environmentally friendly manner.

I will request a refund to your credit card for the $15 price of the product ASAP.

I don’t think any of this needs further elaboration on my part, but I note that Simply NUC has since modified its fans page to be a bit more informative.

Jul 04

Some PSAs for NUC owners

I’ve written before, in Contemplating the Cute Brick, that I’m a big fan of Intel’s NUC line of small-form-factor computers. Over the last week I’ve been having some unpleasant learning experiences around them. I’m still a fan, but I’m shipping this post where the search engines can see it in support of future NUC owners in trouble.

Two years ago I bought an NUC for my wife Cathy to replace her last tower-case PC – the NUC8i3BEH1. This model was semi-obsolete even then, but I didn’t want one of the newer i5 or i7 NUCs because I didn’t think it would fit my wife’s needs as well.

What my wife does with her computer doesn’t tax it much. Web browsing, office work, a bit of gaming that does not extend to recent AAA titles demanding the latest whizzy graphics card. I thought her needs would be best served by a small, quiet, low-power-consumption machine that was cheap enough to be considered readily disposable at the end of its service life. The exact opposite of my Great Beast…

The NUC was an experiment that made Cathy and me happy. She especially likes the fact that it’s small and light enough to be mounted on the back of her monitor, so it effectively takes up no desk space or floor area in her rather crowded office. I like the NUC’s industrial design and engineering – lots of nice little details like the four case screws being captive to the baseplate so you cannot lose them during disassembly.

Also. Dammit, NUCs are pretty. I say dammit because I feel like this shouldn’t matter to me and am a bit embarrassed to discover that it does. I like the color and shape and feel of these devices. Someone did an amazing job of making them unobtrusively attractive.


Last week, Cathy registered a complaint that her NUC was making a funny noise. I went and listened and, alas, it was clearly the sound of the fan bearing in the NUC, screaming. That sound means you have worn or dirty bearing surfaces and the fan could fail at any time, forcing the device to shut down before it roasts its own components.

PSA #1: If you web-search for “NUC fan replacement”, you may well land at the website of a company specializing in NUC sales and support, named “Simply NUC”; I did. Do not buy from these people; they are lazy jerks.

First reason I know this: the “Fans” subpage in their Accessories section carries a link to exactly one model of fan. No indication of the range of NUC variants it matches, and not even a general warning that there are NUC models that require a different-sized fan. I had to find this out the hard way by pulling out the innards of Cathy’s NUC and sitting the fan I bought from Simply NUC next to it.

Two fans side by side

Second reason I know this: Simply NUC tech support was unhelpful, telling me they only carry that one fan and suggesting that I RMA Cathy’s machine back to Intel for repair, because obviously there could be no conceivable problem with it being out of service for an indefinite amount of time.

When I asked if Simply NUC knew of a source for a fan that would fit my 8i3BEH1 – a reasonable question, I think, to ask a company that loudly claims to be a one-stop shop for all NUC needs – the reply email told me I’d have to do “personal research” on that.

It turns out that if the useless drone who was Simply NUC “service” had cared about doing his actual job, he could have the read the fan’s model number off the image I had sent him into a search box and found multiple sources within seconds, because that’s what I then did. Of course this would have required caring that a customer was unhappy, which apparently they don’t do at Simply NUC.

Third reason I know this: My request for a refund didn’t even get refused; it wasn’t even answered.

It actually took some work to get the NUC board and fan out if its case. I watched some YouTube videos purporting to illuminate the process; none of them quite matched the hardware I was looking at and none told me the One Weird Trick I actually needed to know. Therefore:

PSA #2: If you’ve taken out both hold-down screws and the board still seems mechanically locked in place, it may well be because the NUC case is designed like that. On some NUCs you need to flex the two case walls with connector ports outwards by about a millimeter on each side so the connectors will pop out of their exit holes. The case is made of thin, springy metal; thumb pressure will do it.

So now I’m waiting on a second replacement fan to arrive. But there is good news; while I had the thing disassembled I blew out all the dust I could see with a can of air, playing it liberally over the fan. And since I reassembled it, it hasn’t screamed once. So:

PSA#3: Your NUC fan noise problem might be solvable just by blowing out the moondust under and around the fan bearings.

We’ll see. If I’m feeling lazy when the new fan arrives, I’ll leave it in the parts drawer until and unless the one now in the NUC fails. If I’m feeling energetic, I’ll swap in the new one, then disassemble and thoroughly clean and oil the old one before putting it in the drawer.