My favourite German word¶
30th June 2025
A documentation colleague recently challenged me with a question:
Nowadays, more and more people reach for an LLM tool to provide the information they want. If human beings don’t actually read it, what is the point of writing and structuring documentation for humans?
Newer generations (she said) are becoming unskilled at finding information for themselves. They seem less able to digest what they find, to apply it to their problems. But it’s not just that: everybody seems to expect answers that are closely tailored to their particular situation, level of understanding and so on, and to get the answers now. And, many of them are willing to give up guarantees of quality and reliability in exchange of ease-of-use and customised responses.
So why should we take painstaking care in the creation of high-quality documentation?
A lot of recent discussion in documentation circles and forums has swirled uneasily around these topics. A popular and gloomy version of my colleague’s line of thought is: “What is the point of my job?”
Good question.
Gegenstand¶
My favourite word in the German language is Gegenstand, for object or thing.
Gegenstand, “stand-against”. An object is something that stands against you. It’s not you. It’s outside you. It has its own rules. It doesn’t conform to your desires. You run up against it, and it resists.
Objects aren’t just inert stuff – they do something. Even better, Gegenstand shows how objects help define us. I know what I am, what the limits of myself are, because I am able to come up against resistant objects. That’s how I know and have a sense of my own body, its extension in space, where it ends and where the world begins.
I am able to have a self in the first place only because the world of objects is there to stand against me.
The nature of things¶
Gegenstand gives objects and reality a kind of integrity. I have to respect them. They do not yield to my will just because I want them to. They have a nature that belongs to them. If I want to do something with them, I’m going to have to work on their terms to do it.
Reality’s resistance is what makes it possible to work with things at all. Every tool and machine that ever existed worked by being a stubbornly resistant Gegenstand.
Design, fit and resistance¶
Good design is magnificent because it takes resistant materials, unyielding constraints, and successfully gives them a form that works for us.
It’s a pleasure to pick up something – a knife, a camera, anything – that simultaneously fits and resists the hand, in just the right ways. Good clothes fit and resist the body.
The pleasure is not just in the fitting, but in the fitting and resistance.
Bad design¶
Something that resists unpleasantly, like an uncomfortable chair, is bad design. It only resists, and fails to fit. (We have enough of those things in our lives.)
But, bad design is also when things are made to fit too much.
In the 1980s, a strange thing started to happen to physical products, and continues today. The idea that objects should fit to human needs began to be interpreted as meaning that they should literally fit the shape of the hand. Parts of everyday products – on bicycles, umbrellas, cameras – were increasingly given hand-shaped grips.
A camera today will often have a grip closely contoured to the fingers of the hand. In one way this does make the camera easier to hold – but literally only in one way. Only with the right hand, and only in one particular way, so tough luck if that doesn’t suit you – for example if you have a physical disability. Holding it any other way (and there are many good ways of holding a camera) is made more difficult, unsafe and uncomfortable. (Similarly, the asymmetric computer mice that became popular a couple of decades ago were as unpleasant in the left hand as a shoe on the wrong foot.)
These objects are over-fitted.
Servile objects¶
Our hands, that evolved over millions of years, can hold almost any suitably-sized object safely and comfortably. Things don’t need to be specially fitted to the hand; our hands are happy to meet and hold anything that doesn’t actively resist them.
In fact, they don’t want objects to be over-fitted. Over-fitted objects are servile. They have a creepy character. They are craven and eager to please, and give up their own confidence of form, that would allow us, with our splendidly adaptive hands, to hold them in multiple different ways. Their design doesn’t actually help us. It looks like the object has been designed to fit to the needs of the hand, but in fact it’s a false friend – it’s the hand that is obliged to conform to the object’s single idea of how it should be held.
People¶
The same principles apply to our relationships with people. People must be Gegenstände, who stand against you because they have their own integrity, and do not conform to what you want just because you want it.
A friend is a person who fits and resists in the right way, someone you can to stand against to measure yourself by them. A friend is not someone who only fits.
Like an object that relinquishes its own integrity, a person who moulds themselves against you is creepy - a false friend.
Knowledge and information¶
Knowledge and information are Gegenstände too.
They have their own rules. Integrity and resistance to our will are part of their nature. When they fit our needs, we are delighted – but if they become servile, made to conform to what we want them to be, they lose their worth. A news source that only tells us what we want to hear is as dangerous and treacherous as a person who does.
Sometimes we might not want them to, but we need knowledge and information to stand against us, as objective things, so we can have a healthy relationship with them.
Information in space¶
Because they are Gegenstände, our relationship with them is spatial.
We ask where information is, and we organise it in space. It’s not a coincidence or metaphor that we use the language of searching and finding, or that we have concepts like information architecture.
In the history of the world, every library has had an information architecture, and a librarian to maintain it.
Information architecture organises knowledge in an information space, in which everything has a place, and places all knowledge in relation to other knowledge – in spatial relations, of hierarchy, opposition, distance, closeness and adjacency, of intersection and overlap. It’s not merely an arrangement applied to knowledge: the organisation of knowledge is part of knowledge itself.
It’s also part of our own relationship with knowledge. Many people still know, decades after their studies, exactly where in a book some important material is to be found. Everything in my own university library was in a place, a hierarchy of floors and sections and shelves, and that’s how I knew it. I moved around, in the information.
Its structure was its own, an active, rational principle of organisation. It wasn’t always what I wanted or convenient for me, but it was a structure, that I had to understand so that I could navigate it, to find the knowledge where it was. If I wanted something from the library, I had to work on the library’s terms to get it.
Experiences of knowledge¶
Because of the library’s rational hierarchical structure of information, I had many experiences of knowledge.
Adjacent knowledge; I would discover something important because I was physically near the the thing I was looking for. Surprise knowledge. Knowledge encountered on the way to something else. Sometimes, knowledge that threw a spanner in the works and that I wasn’t pleased to find but couldn’t ignore.
Experience in knowledge¶
The handbook I was given to accompany the introductory five-day Python/Django course I took in 2009 served as my first port of call for Python reference for the next few years. It was open permanently on my desk and I used it daily in my work.
It wasn’t successful in that role because it had an ideal information structure. In fact it didn’t; as a workbook for a course, it took a linear path, more adapted to a learner’s progression than to being used as a reference guide. It succeeded because it had a definite information structure, rational and clear enough that I could find my place and make my way in it. To become an effective user of it, I had to come to terms with it, and acquire a mental model of its arrangement.
Our brains are as adaptable to different shapes as our hands, and the handbook was comfortably usable in that way.
Its structure didn’t just permit me to find the information I needed in effective ways. It asserted relationships (of dependency, consequence, progression, hierarchy) within the knowledge it contained. It was an inextricable element of my relationship with it; as far as I was concerned, part of the information itself.
Diminished powers¶
As a university teacher a long time ago, I observed at first hand how students discovered knowledge, and saw how it changed when the web came along.
I saw that students who had learned to find information by searching through card indexes and other tools that asserted the whereness of information were much more effective discoverers than the ones for whom web search was their starting point. I don’t mean they were more effective in using things like card indexes – I mean that they were better at looking for knowledge in general, and in particular, also better at using the web to search for it.
The strategies and execution of their searching were more sophisticated. Their judgements were more critical. They were able to articulate their purposes, experiences and results more effectively. I watched each new cohort of students adopt increasingly crude approaches to knowledge discovery, expressed both in the language they used and what they had to show for their efforts.
It happened astonishingly fast; within about five years a knowledge skill that I had completely taken for granted as a basic requisite in an undergraduate was diminished beyond recognition.
Diminished encounters¶
I noticed another effect. A teacher can see evidence of students’ experiences and encounters of knowledge. Those things would appear tangibly in their work. Sometimes I would recognise a particular book they had taken out of the library, that happened to be physically close on the shelves to something else on their reading lists. (More than once, I realised a student had made the same chance discovery that I had as an undergraduate. I felt the kind of thrill you feel when discovering that someone shares your taste in music or art.)
Later, as they used more material that they had found and read electronically, I saw fewer of these particular and recognisable experiences expressed in the work they produced. Their work became smoothed out, and more like each others’. They had ever more material at their fingertips, and used less, and knew less about it, and were less confident about what they could or should use.
They rarely picked up adjacent knowledge, because things weren’t adjacent any more. They had fewer chance encounters with knowledge, and they surprised me less. Everything they found was equally close to everything else; they were being denied the physical, spatial clues that are part of the experience of knowledge.
Standing up for knowledge¶
All this is to insist that knowledge and information must be objects in our world, Gegenstände, and that their being something that can stand against us is essential to their nature.
As objects, information must be well-designed – structured and created to fit and resist in the right ways. Everything that is strong, enduring and empowers us in our relationship with knowledge recognises that. The designer of good information understands it implicitly, just as the designer of good objects does.
The convenience of web searches has eroded some of our deeper relationships with knowledge, particularly in those who have not already acquired a strong sense of its spatial nature. As the colleague who prompted this discussion pointed out, in the age of LLM-first information discovery, those relationships are at new risk.
People are starting to expect machines to provide them not merely with sources containing the information they want, but direct answers to the questions they have. The idea of a source of information is being undermined.
Blobs¶
The information that comes to me mediated by AI is in discrete pieces, that have budded off from a larger body of information. They come as a series of information-units, created to mould themselves to what I want at that moment. They are eager to please. They will immediately remould themselves to me if I ask for something a little different, or resist them: non-reproducible answers to specific problems, each one a blob that exists on its own for that moment.
This is over-fitted information, too servile to resist me, too weak to demand that I meet it on its terms, or to stand against me. It’s a false friend, ready to follow my shape as closely as I want.
Information that changes its shape before our eyes, a slightly different version each time, advertises its own treachery. It’s non-deterministic. This is no way for documentation, that should command authority, to behave.
Information for skills¶
People must be skilled and empowered in the crafts of their work. I believe that holds as an absolutely fundamental value of work.
Even if you don’t share the same values as me, perhaps you will recognise this principle on purely practical grounds. If not, please consider what skill means to you the next time someone is preparing a meal for you, or flying the aircraft you are a passenger in.
The purpose of documentation is to skill and empower someone in their craft. It serves their acquisition and application of skill.
I have heard it suggested that documentation should now be optimised for consumption by AI. That is like asking how we can make our cities better for cars, or our workplaces better for the furniture.
If creators of documentation are prepared to sacrifice its human purpose in order that LLMs can more effectively slurp it up and regurgitate it on demand, then they have meekly accepted values that more properly belong in a dystopian horror story.
Even if we think about the notion only pragmatically, leaving all values aside, it’s a panicky, inconsidered idea. What possible sense does it make to try to “write for LLMs” when LLMs themselves are evolving so rapidly that their capacities and patterns change from one week to the next?
Human beings are difficult creatures with complex needs, but they have been that kind of creature for thousands of years. Not only have we painstakingly built up deep understanding of them, we are them; we can know them from the inside. A good way of writing documentation for human beings today will still be a good way to do it in a few years’ time.
Users’ needs and wants¶
The duty of documentation is to serve users’ needs. Sometimes, that might not be the same as users’ wants, or even be what they think they need. It’s a tricky place to be, making judgements about what other people need, especially when they tell us it’s not what they want.
But just because it’s difficult and risky to do that doesn’t mean we should never try to do it.
If documentation creators are information experts then it’s our duty and business to know these things, and to believe in our own expertise and authority. It’s not good enough to retreat to the safety of prevailing opinions on those matters.
If we care about our discipline and think it is, in fact, a real one worth the name, we must be prepared to reason and argue, publicly and effectively, about its values and its practice.
If there are good ways of doing things, then we need to believe in them and ourselves enough to educate others about them. And if we can’t do that, we might as well give up and go back home.
“What is the point of my job?” indeed.
At any given moment vs. the long run¶
It’s true: on every single occasion, what I wanted to know and had to retrieve from my Python handbook could probably have been provided to me more quickly and efficiently in the form of a direct answer to my question. I would have been able to stop looking for the information sooner. I would not have needed to work out how to apply it to my work. I could have arrived at the result I wanted, more swiftly and effectively. At any given moment, that would have been faster and more productive.
At any given moment, yes, but not over the course of those years of work as a whole. The information contained in the documentation became part of my skill when and only because it was discovered, read, assimilated, questioned and applied by me, as I navigated through its information-space. That labour and experience was an essential part of my becoming empowered, of my acquisition and refinement of skill.
Everyone who has acquired a skill recognises that they acquired it through an effort that was a necessary aspect of the acquisition of it. (Strangely we still often hope that when it comes to some new skill, we might somehow be exempted, just this once, from the law of nature that demands it every time. That’s human nature too.)
Passivity¶
Documentation practitioners, for whatever reason, tend towards the passive. Largely, they accept the products they document as they are; they don’t believe it’s their place to make a difference to the product (nor are they often invited to).
And, often, they rather passively accept the expectations that are placed on them and their work. They permit their role to be reactive, serving demands rather than asserting value. I think that’s not enough.
A self-respecting librarian, confident in their own discipline, says: Here is the library, here is the information; it is arranged so; you will need to learn how it’s arranged, and how it works.
We should be able to say: this is how documentation is, because this arrangement is part of its integrity, and this is how you must learn to use it and work with it.
The value of documentation¶
Documentation does not have value as an expedient answer to a particular question in a particular moment.
Documentation has value as a rational territory of knowledge, one that can be discovered, inhabited, navigated and returned to because it occupies an organised information space. It has value when it has been designed to fit and resist in ways that mean we can grasp it with confidence.
To do that it must be part of a world of information Gegenständen for its users, to serve our skill without ever being servile, to stand against us with integrity.
That is the point of your job.