John Naughton linked to a splendid post by my friend and erstwhile colleague Alan Blackwell, entitled “Oops! We Automated Bullshit.“
I won’t try to summarise it here, or even discuss the topics he raises, because you should cetainly go and read the article. But I did like the aside where he questions his own use of the word “literally”:
Do I mean “literally”? My friends complain that I take everything literally, but I’m not a kleptomaniac.
“A work of art”, so the saying goes, “is never finished, merely abandoned.”
This assertion rings true in many artistic spheres, to the extent that I’ve seen variations attributed to people as diverse as Leonardo da Vinci and W.H.Auden.
The site ‘Quote Investigator’ suggests that it actually originated in a 1933 essay by the poet Paul Valéry:
Aux yeux de ces amateurs d’inquiétude et de perfection, un ouvrage n’est jamais achevé, – mot qui pour eux n’a aucun sens, – mais abandonné …
and they offer this approximate translation:
In the eyes of those who anxiously seek perfection, a work is never truly completed—a word that for them has no sense—but abandoned …
My knowledge of French idiom falls short of telling me how significant Valéry’s use of the word ‘amateur’ is, though. Is he saying that it’s the professionals who really know when a work is complete?
~
Anyway, the same original core assertion is sometime used when speaking of software: that it’s never finished, only abandoned.
It’s rare that any programmer deems his code to be complete and bug-free, which is why Donald Knuth got such attention and respect when he offered cheques to anyone finding bugs in his TeX typesetting system (released initially in the late 70s, and still widely-used today). The value of the cheques was not large… they started at $2.56, which is 2^8 cents, but the value would double each year as long as errors were still found. That takes some confidence!
He was building on the model he’d employed earlier for his books, most notably his epic work, The Art of Computer Programming. Any errors found would be corrected in the next edition. It’s a very good way to get diligent proofreaders.
Being Donald Knuth does give you some advantages when employing such a scheme, though, which others might want to consider before trying it themselves: first, there are likely to be very few errors to begin with. And second, actually receiving one of these cheques became a badge of honour, to the extent that many recipients framed them and put them on the wall, rather than actually cashing them!
For the rest of us, though, there’s that old distinction between hardware and software:
Hardware eventually fails. Software eventually works.
~
I was thinking of all this after coming across a short but pleasing article by Jose Gilgado: The Beauty of Finished Software. He gives the example of WordStar 4, which, for younger readers, was released in the early 80s. It came before WordPerfect, which came before Microsoft Word. Older readers like me can still remember some of the keystrokes. Anyway, the author George R.R. Martin, who apparently wrote the books on which Game of Thrones is based, still uses it.
Excerpt from the article:
Why would someone use such an old piece of software to write over 5,000 pages? I love how he puts it:
“It does everything I want a word processing program to do and it doesn’t do anything else. I don’t want any help. I hate some of these modern systems where you type up a lowercase letter and it becomes a capital. I don’t want a capital, if I’d wanted a capital, I would have typed the capital.”
— George R.R. Martin
This program embodies the concept of finished software — a software you can use forever with no unneeded changes.
Finished software is software that’s not expected to change, and that’s a feature! You can rely on it to do some real work.
Once you get used to the software, once the software works for you, you don’t need to learn anything new; the interface will exactly be the same, and all your files will stay relevant. No migrations, no new payments, no new changes.
I’m not sure that WordStar was ever ‘finished’ , in the sense that version 4 was followed by several later versions, but these were the days when you bought software in a box that you put on a shelf after installing it from the included floppies. You didn’t expect it to receive any further updates over-the-air. It had to be good enough to fulfill its purpose at the time of release, and do so for a considerable period.
Publishing an update was an expensive process back then, and we often think that the ease which we can do so now is a sign of progress. I wonder…
I’m old enough that I can remember going into London to see the early launch demos of Microsoft Word for Windows. I was the computer officer for my Cambridge college at the time, and, up to that point, everyone I was helping used Word for DOS, or the (arguably superior) WordPerfect.
These first GUI-enabled versions of Word were rather good, but the features quickly piled on: more and more buttons, toolbars, ribbons, bells and whistles to persuade you, on a regular basis, to splash out on the next version, unwrap its shrink-wrapped carton, and install it by feeding an ever-increasing number of floppy disks into your machine.
And so for some of us, the trick became learning how to turn off and hide as many of these features as possible, partly to avoid confusing and overwhelming users, and partly just to get on with the actual business of creating content, for which we were supposed to be using the machines in the first place. One feature which became the iconic symbol of unwanted bloatware was ‘Clippy’ (officially the Office Assistant), which was cute for about five minutes and then just annoying. For everybody. We soon found the ‘off’ switch for that one!
These days, I very seldom use any Microsoft software (other than their truly excellent free code editor, VSCode, with which I earn my living), so I certainly haven’t sat through any demos of their Office software since… well, not since a previous millennium.
But today, since it no longer involves catching a train into London, I did spend ten minutes viewing their demo of ‘Microsoft 365 Copilot’ — think Clippy endowed with the facilities of ChatGPT — and I recommend you do too, while remembering that, as with Clippy, the reality will almost certainly not live up to the promise!
Still, it’s an impressive demo (though somewhat disturbing in parts) and though, like me, you may dismiss this as something you’d never actually use, it’s important to know that it’s out there, and that it will be used by others.
ChatGPT is famous for producing impressively readable prose which often conceals fundamental factual errors. Now, that prose will be beautifully formatted, accompanied by graphs and photos, and therefore perhaps even more likely to catch people unawares if it contains mistakes.
The text produced by these systems is often, it must be said, much better than many of the things that arrive in my inbox, and that will have some advantages. One challenge I foresee, though, is the increasing difficulty in filtering out scams and spams, which often fail at the first hurdle due to grammatical and spelling errors that no reputable organisation would make. What happens when the scammers have the tools to make their devious schemes grammatically correct and beautiful too?
I would also be interested to know how much of one’s text, business data etc is uploaded to the cloud as part of this process? I know that most people don’t care too much about that — witness the number of GMail users oblivious to the fact that Google can read absolutely everything and use it to advertise to them and their friends — but in some professions (legal, medical, military?), and in some regimes, there may be a need for caution.
But it’s easy to dwell on the negatives, and it’s not hard to find lots of situations where LLMs could be genuinely beneficial for people learning new languages; struggling with dyslexia or other disabilities; or just having to type or dictate on a small device a message that needs to appear more professional at the other end.
In other words, it can — to quote the announcement on Microsoft’s blog page — help everyone to ‘Uplevel skills‘.
Good grief. Perhaps there’s something to be said for letting the machines write the text, after all.
One of the great benefits of the internet, of course, is its ability to give you a smug sense of satisfaction when you find others who agree with your point of view. This can be further enhanced after a short period if you feel that historical events have actually proved you were right all along.
So powerful is this effect that I’ve just been to check whether the domain IToldYouSo.com was still available. But it wasn’t. “Well”, you’re probably saying, “I could have told you that…”
I can’t help wondering whether, if you added it up on a global scale, the tears shed in recent days over the collapse of the FTX crypto exchange have been balanced by all the small self-affirming boosts for those of us who always felt this cryptocurrency stuff was too good to be true, and are now experiencing emotions somewhere between Schadenfreude and “There but for the grace of God…”!
The key technology behind most cryptocurrencies is, of course, the blockchain: a distributed ledger consisting of entries that are like the laws of the Medes and Persians; once written, they cannot be changed. What’s more, this system doesn’t require you to trust Medes, Persians or anyone else to maintain it because this ledger is distributed over many tens of thousands of independent machines. It’s often described as a zero-trust system.
It’s particularly appealing to conspiracy theorists who distrust all big corporations and governments, and also to those who live in regimes that are genuinely untrustworthy, or where the rule of law is not well-established. Once your purchase, contract, will, marriage certificate, patent application or whatever is recorded on a blockchain, there’s theoretically nothing anybody can do to get rid of that record. I’m reading Nineteen Eighty-Four again at the moment, and one of the keys to The Party’s absolute power in that book is their ability to rewrite history at any time, and erase all evidence of having done so. Not so with blockchains!
Sounds wonderful, doesn’t it? Especially if you ignore for now the fact that most implementations turned out to be phenomenally power-hungry to run. It is a clever technology, and quite apart from the ridiculous amounts of cash that have been converted to and from cryptocurrencies and similar gambles like NFTs, huge amounts have also been invested in startups that are building things using blockchain technologies.
But there’s a problem.
In its first 14 years, at least, despite vast amounts of interest and investment, it’s been very hard to identify more than a small handful of real use cases of the blockchain. (The Cambridge Centre for Carbon Credits is run by very smart friends of mine, and may well prove to be an example of a great application.)
But in general, yes, there are lots of things you can build using Distributed Ledger Technologies (to give the more formal generic term), and there are many systems that would probably be better if they were built that way, but it almost always turns out to be much easier just to use a database and trust somebody! If you don’t want to trust any individual organisation, then you can create an industry-wide standards body or something similar to run your database.
Sometimes you might use an irreversible ledger, but again, if you can just trust somebody to look after it, you can avoid all that nasty messing about with the complexity and environmental impact of the proof-of-work algorithm: the normal way of avoiding the need for trust.
All of the above is a very long introduction to Tim Bray’s interesting article about how Amazon’s AWS team, providers of the largest computing facilities in the world, basically came to the same conclusion about blockchains as I did, which made me feel smug.
History, of course, may tell a different story, but I’ll have edited this blog post by then, because it’s in a database.
Thanks to John Naughton and Charles Arthur, both of whom linked to Tim’s article.
This is a very geeky post for those who might be Googling for particular details of Linux containerisation technologies. Others please feel free ignore! We were searching for this information online today and couldn’t find it, so I thought I’d post it myself for the benefit of future travellers…
In your Dockerfile, you can specify a HEALTHCHECK: a command that will be run periodically within the container to ascertain whether it seems to be basically happy.
A typical example for a container running a web server might try and retrieve the front page with curl, and exit with an error code if that fails. Something like this, perhaps:
HEALTHCHECK CMD /usr/bin/curl --fail http://localhost/ || exit 1
This will be called periodically by the Docker engine — every 30 seconds, by default — and if you look at your running containers, you can see whether the healthcheck is passing in the ‘STATUS’ field:
$ docker ps
CONTAINER ID IMAGE CREATED STATUS NAMES
c9098f4d1933 website:latest 34 minutes ago Up 33 minutes (healthy) website_1
Now, you can configure this healthcheck in various ways and examine its state through the command line and other Docker utilities and APIs, but I had always thought that it wasn’t actually used for anything by Docker. But I was wrong.
If you are using Docker Swarm (which, in my opinion, not enough people do), then the swarm ensures that an instance of your container keeps running in order to provide your ‘service’. Or it may run several instances, if you’ve told the swarm to create more than one replica. If a container dies, it will be restarted, to ensure that the required number of replicas exist.
But a container doesn’t have to die in order to undergo this reincarnation. If it has a healthcheck and the healthcheck fails repeatedly, a container will be killed off and restarted by the swarm. This is a good thing, and just how it ought to work. But it’s remarkably hard to find any documentation which specifies this, and you can find disagreement on the web as to whether this actually happens, partly, I expect, because it doesn’t happen if you’re just running docker-compose.
But my colleague Nicholas and I saw some of our containers dying unexpectedly, wondered if this might be the issue, and decided to test it, as follows…
First, we needed a minimal container where we could easily change the healthcheck status. Here’s our Dockerfile:
FROM bash
RUN echo hi > /tmp/t
HEALTHCHECK CMD test -f /tmp/t
CMD bash -c "sleep 5h"
and we built our container with
docker build -t swarmtest .
When you start up this exciting container, it just goes to sleep for five hours. But it contains a little file called /tmp/t, and as long as that file exists, the healthcheck will be happy. If you then use docker exec to go into the running container and delete that file, its state will eventually change to unhealthy.
If you’re trying this, you need to be a little bit patient. By default, the check runs every 30 seconds, starting 30s after the container is launched. Then you go in and delete the file, and after the healthcheck has failed three times, it will be marked as unhealthy. If you don’t want to wait that long, there are some extra options you can add to the HEALTHCHECK line to speed things up.
OK, so let’s create a docker-compose.yml file to make use of this. It’s about as small as you can get:
version: '3.8'
services:
swarmtest:
image: swarmtest
You can run this using docker-compose (or, now, without the hyphen):
docker compose up
or as a swarm stack using:
docker stack deploy -c docker-compose.yml swarmtest
(You don’t need some big infrastructure to use Docker Swarm; that’s one of its joys. It can manage large numbers of machines, but if you’re using Docker Desktop, for example, you can just run docker swarm init to enable Swarm on your local laptop.)
In either case, you can then use docker ps to find the container’s ID and start the healthcheck failing with
docker exec CONTAINER_ID rm /tmp/t
And so here’s a key difference between running something under docker compose and running it with docker stack deploy. With the former, after a couple of minutes, you’ll see the container change to ‘(unhealthy)’, but it will continue to run. The healthcheck is mostly just an extra bit of decoration; possibly useful, but it can be ignored.
With Docker Swarm, however, you’ll see the container marked as unhealthy, and shortly afterwards it will be killed off and restarted. So, yes, healthchecks are important if you’re running Docker Swarm, and if your container has been built to include one and, for some reason you don’t want to use it, you need to disable it explicitly in the YAML file if you don’t want your containers to be restarted every couple of minutes.
Finally, if you have a service that takes a long time to start up (perhaps because it’s doing a data migration), you may want to configure the ‘start period’ of the healthcheck, so that it stays in ‘starting’ mode for longer and doesn’t drop into ‘unhealthy’, where it might be killed off before finishing.
Previously on Status-Q…
Regular readers may remember that a couple of months ago, I lost my glasses and found them again. If you missed that particularly gripping episode, turn back to Location, location, location (or, ‘How technology saved me a few hundred quid yesterday’) and then you’ll understand the background here.
After posting it, my friend Phil Endecott got in touch with me. “Am I to understand”, he said, “that you would find it useful if you had a map app that could show both the locations of your photos and your current location at the same time? If so, I may have just what you need….”
And he did indeed. Phil, you see, is the author of UK Map, an iOS app that I’ve had for as long as I can remember, and one I should talk about more, because I use it all the time, especially when looking for new dog-walking routes. Yes, I may use Google Maps to find out how long it’ll take me to drive there, and Streetview to check that there’s likely to be a parking spot when I get there, but once I’ve laced up my walking boots, then I generally switch to UK Map. It combines free or paid-for Ordnance Survey maps with footpaths from Open Street Map, and, certainly round here, it’s a much better guide than almost anything else as to where you can actually go for a walk.
New features get added periodically and, like much of the cool stuff, are often buried deep in some menu below some unassuming icon in the corner, making them very easy to miss, so you really do want to go to the home page and read it carefully to see what the app can do, and then to the help button in the app to see how to do it. I don’t check these often enough, but when Phil’s message prompted me, I had another explore and found that, yes, it can show your photos on your maps. This is the site of my aforementioned adventure:
and if I had been there at the time of writing this, the little blue dot would indeed have shown me exactly what I needed to know. (The violet-coloured triangle there, by the way, is showing the rough direction in which the phone was pointing when it took the picture, and therefore shows what you may be able to see in it. Neat, eh?)
Anyway, I’ve mentioned UK Map before, but I’ve used it for so many years that I take it for granted. I do think that if you put in a little time learning what it can do, you’ll find it repays its very modest purchase price. Actually, it’ll repay that even if, like me, you really only scratch the surface.
P.S. If you happen to be anywhere other than the UK, this will be of limited use, but if you’re in North America, Phil is also the author of the highly-rated Topo Maps
Back in about 1993, I was doing the bookkeeping for a big project being undertaken by my local church. Donations were flooding in, and we needed to keep track of everything, send out receipts, forms and letters of thanks, and note whether each donation was eligible for the UK tax relief known as ‘Gift Aid’.
I was keeping track of this using on a PC running the now long-gone Microsoft Works, which, for those less familiar with last-millennium computing, was a software suite incorporating basic and much cheaper versions of the things you found in Microsoft Office: a word-processor, database, and spreadsheet. If your needs were simple, it worked rather well.
Anyway, at one point I was printing out a list of recent donations on my dot-matrix printer, and I noticed what appeared to be some data corruption. In the midst of the sea of donors’ names, there were a couple of dates being printed out. Was this a software bug, or was my database file corrupt? I started investigating, while wondering just how much data I’d entered since my last backup and whether I could recreate it…
In the end, the answer was simple, and I breathed a huge sigh of relief. I tried recreating the entry for one of donors and the same thing happened again, at which point I dug a bit deeper and discovered a ‘feature’ of the app. The lady’s first name was ‘June’, and, though it displayed just fine on the data-entry screen, behind the scenes, it had been turned into 1/6/93! I skimmed quickly through the congregation to find the other problematic record, and found it was for a donation from a lady named ‘May’!
When I came back to doing some scientific computing in academia a few years ago, I was surprised and slightly worried to see several of my colleagues processing their data with Excel. It’s a wonderful program and very appealing, because of the ease of viewing, checking and plotting graphs of your results, but it comes with lots of problems of its own and shouldn’t be used as a substitute for a proper database (if you’re a church accountant), or for something like Jupyter Notebooks, if you’re a scientific researcher, unless you’re exceedingly careful. Last year, more than a quarter of a century after my issues with May and June, 27 human genes were actually renamed because of the number of errors caused in scientific papers by the use of Excel by researchers. The genes’ previous names were things like ‘SEPT1’.
All of this came to mind when reading Tim Harford’s enjoyable piece in yesterday’s FT, The Tyranny of Spreadsheets. Harford follows the origins of spreadsheets, double-entry bookkeeping and other ways of keeping track of things, up to the famous case last year where 16,000 people weren’t promptly told they had positive Covid test results, because somebody had used Excel’s old XLS file format, which can only store about 64,000 rows of information, instead of the newer XLSX. That’s not really a problem; the problem is that Excel doesn’t give you adequate warning when it’s discarding data, or changing it in an attempt to be helpful. And the results can be serious.
To quote the article:
Two economists, Thiemo Fetzer and Thomas Graeber … decided that no catastrophe should be allowed to occur without trying to learn some lessons. They combed through the evidence from Public Health England’s mishap. And by comparing the experiences of different regions, they concluded that the error had led to 125,000 additional infections.
…
Fetzer and Graeber have calculated a conservative estimate of the number of people who died, unknown victims of the spreadsheet error. They think the death toll is at least 1,500 people.
Think about that, as you click ‘Save As…’ and pick your data format.
(Thanks to my sister-in-law Lindsey for the link to the Harford article, which also traces some of the origins of spreadsheets from the 14th century; that’s before even I was using them!)
Like many people of approximately my generation, I have long been an advocate of David Allen’s famous ‘Getting Things Done‘ methodology. In case you’ve been living in a cave for a couple of decades and haven’t come across ‘GTD’, it was an appealing and genuinely useful system for handling, originally, the ever-growing flood of paperwork that people were experiencing towards the end of the last millennium. Allen was fortunate (or canny) in that most of his book, originally published in 2001, translated very nicely into the emerging predominantly-digital world. He did for filing cabinets and in-trays what Marie Kondo now does for wardrobes and sock drawers.
Over the following couple of decades, many software products sprang up to help you adapt the GTD task-management techniques to your new digital world; the most complete and sophisticated probably being OmniFocus. If you juggle lots of big and complex projects and are really into this stuff, OmniFocus is immensely capable, and I started using it as soon as it was first available as a beta release about 13 years ago. I typically have two or three part-time jobs at any one time, and many projects within each one, and something like OmniFocus can definitely help keep your world manageable especially if, like me, your brain is not one that is naturally drawn to rigorous and careful planning and organisation! In recent months, though, I’ve switched to the rather wonderful ‘Things‘, which is for me the perfect half-way point between a simple to-do list and the all-encompassing and baroque structures I had previously created within OmniFocus.
Anyway, all of this meant that I was very interested when John linked to this New Yorker piece by Cal Newport, talking about the history of GTD and some of its limitations in the current climate. It’s a good read; here are a couple of short extracts:
In this context, the shortcomings of personal-productivity systems like G.T.D. become clear. They don’t directly address the fundamental problem: the insidiously haphazard way that work unfolds at the organizational level. They only help individuals cope with its effects. A highly optimized implementation of G.T.D. might have helped Mann organize the hundreds of tasks that arrived haphazardly in his in-box daily, but it could do nothing to reduce the quantity of these requests.
…
It seems likely that any successful effort to reform professional life must start by making it easier to figure out who is working on what, and how it’s going. Because so much of our effort in the office now unfolds in rapid exchanges of digital messages, it’s convenient to allow our in-boxes to become an informal repository for everything we need to get done. This strategy, however, obscures many of the worst aspects of overload culture. When I don’t know how much is currently on your plate, it’s easy for me to add one more thing. When I cannot see what my team is up to, I can allow accidental inequities to arise, in which the willing end up overloaded and the unwilling remain happily unbothered.
In a distributed working-from-home world, he argues, techniques like Kanban boards — or the electronic versions encapsulated in products like Trello — can be more appropriate ways to manage tasks when your workforce is distributed. You need to make your to-do list more public, so others in your organisation, and particularly those responsible for managing you, can see what you’re working on and whether you have too much (or too little) on your plate. Software developers have been doing this for years, of course, but it’s interesting to think about how many other kinds of work might benefit from some of our techniques in the Covid age.
My favourite example of a public to-do list, though, probably just predated the publication of GTD, and was not digital, even though I was working in a cutting-edge high-technology lab at the time.
The sysadmins — about four of them, I think — all worked in a shared office, and people like me would wander in and ask them to do things which, of course, always needed to be done immediately if they possibly could. So at one point, they adopted a brilliant scheme.
On the wall outside their office, they put up a big board showing the queue of things that people had asked them to do. If you came in with a request, they’d say ‘Sure! We can do that!’, and hand you a little card. You’d write your name and your request on the card and go and pin it on the board at the bottom of the queue. When one of them finished dealing with the current issue, they’d go and take the next card off the board. If you felt that your card was more important than some of the other ones there, you could try to make the case that the queue should be re-ordered. But if the queue was really long, you sometimes discovered that actually you didn’t need this as much as you thought you did, or perhaps you could sort it out yourself.
It was, of course, just a ticketing system, but run very much on a first-come, first-served basis and, since the tickets were all public, it was one which gave everybody, not just management, a very clear idea of what was going on. I’ve always thought it was brilliant, and something which should be replicated more often in the digital world.
Question 1. Which of the following are indicated by having a ‘Knowledge Base’ on your company’s ‘support’ pages?
(a) A lack of the discipline needed to write proper documentation.
(b) Insufficient staff to provide proper support.
(c) Inadequate engineers to provide a reliable product.
(d) A poor user-interface experience in your product.
(e) All of the above.
The best thing about creating a website in blog format, I’ve always thought, is that you don’t need to maintain it to nearly the same degree as you would most other sites. Why? Because everything has a date, and that date is paramount; it is clearly marked. This makes it obvious to the reader that a post was written in a particular context, and, while the content may still be useful some years later, you can’t blame the author for not being able to predict the future if it’s no longer accurate or relevant now! As an author, therefore, you don’t need to be constantly re-reading, deleting, updating, clarifying, as you would with most other forms of documentation.
The appeal of the so-called ‘Knowledge Base’ — a searchable database of support articles on a company website — is that it also promises an alternative solution to this challenge of maintaining structured documentation, but instead of using old Father Time to winnow out inaccurate material, it uses a search engine to help you ignore it.
If you force your customers to type things into the Knowledge Base search box before you let them get anywhere near the page with your phone numbers or email addresses, there’s even a chance they may find out the answer to their question and not bother you! Bliss!
Search engines are wonderful things, of course, and this isn’t a bad idea in theory, but if your experience is anything like mine, these knowledge bases are chiefly a source of frustration for customers.
Why is this?
Users don’t know what to search for. They may not know the phrases you use internally to categorise certain issues. A human support person would know that when you said you had an issue with your mouse, you might be referring to a problem labelled ‘trackpad’ or ‘cursor’ in the docs.
The articles aren’t well-indexed. Do you, for example, make sure that the error message the user actually sees appears in plain text in the articles, so the search engine has a chance of finding it? Do your articles have extensive tagging with relevant keywords which may not be in the text? If the error is slightly different because they used a different filename, will it still be found?
The search engines aren’t good enough. We’ve been spoiled by Google. Does your search engine understand synonyms? Does it rank pages well? Does it show a good summary so your users don’t have to read all 26 articles returned by their query?
The content is outdated. If the user actually succeeds in finding a relevant article, is it clear that it only refers to version 4.2 of the product running on Android, and not version 5.0 running on iOS, because the latter didn’t exist at the time it was written? Will they know that the solution it proposes can’t possibly work for them? Because this advice is buried in a database, it may be harder for your support staff to know this is a problem.
I have four pieces of advice for anyone who has, or is considering implementing, a Knowledge Base on their website:
Make sure the full text of your knowledge base is searchable by Google. They will do a better job than you do.
Allocate more, not less, in the way of resources, if you want your documentation in this form. Knowledge Bases are not like blogs. You can’t dump things in there and forget them. Articles need to be reviewed, re-written, re-indexed, re-keyworded and regularly purged if the contents are to remain useful. You need to do this in addition to writing the actually text itself. Customers will not thank you for anything which suggests you believe that their time is much less important than yours. If they have to search through dozens of articles to try and find an answer, it probably indicates you aren’t doing your job. There may be good reasons for using this format for your documentation. Cheapness isn’t one of them.
If you insist on putting your users through this and they still contact you, you should provide better support once they do. For heaven’s sake, don’t just connect them to somebody in a remote location who only has access to the same information! Don’t offer a chat link to somebody who is ‘Very sorry to hear about your problem’ but knows less about it than they do. Connect them to the engineers who produced the flawed product, or the writers who produced the inadequate documentation.
This is the key one: The bigger your Knowledge Base, the worse job you are doing. In most situations, an entry in your Knowledge Base indicates a failure in communication elsewhere. Insufficient documentation, unhelpful errors, unreliable products. Your users won’t generally be consulting a Knowledge Base if everything is going well for them. Treat it as an issue-ticketing system, and reward those whose work means that articles can be removed from it. And make sure you have the processes in place that this actually happens!
Some people, when confronted with a problem, think ‘I know, I’ll use multithreading’.
Nothhw tpe yawrve o oblems.
Eiríkr Åsheim
I’ve just uploaded my longest YouTube video yet!
Entitled The Modern Lab Notebook: Scientific computing with Jupyter and Python, it’s a two-and-a-quarter hour blockbuster! But you can think of it as three or four tutorial seminars rolled into one: no need to watch it in one sitting, and no need to watch it all! It starts with the basics, and builds up from there.
It’s intended for people who have some Python programming experience, but know little about the libraries that have become so popular recently in numerical analysis and data science. Or for people who may even have used them — pasted some code into a Jupyter notebook as part of a college exercise, say — but not really understood what was going on behind the scenes.
This is for you. I hope you find it useful!
Watch it full-screen, and turn the resolution up 🙂
Also available on Vimeo.
© Copyright Quentin Stafford-Fraser
RSS feed
Recent Comments