💾 Archived View for splint.rs › documentation.gmi captured on 2024-07-08 at 23:57:14. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

"Documentation and Washing with Soap"

My grandmother had thirteen children. Each one was produced by her leaving in a taxi, and returning not-pregnant, and with a child. It’s not that the waiting room was too close for comfort - someone had to stay to look after the children. On one of these occasions, my grandfather had to cook for the children. He took out the simple instructions he had been left (he was very proud of having recently learned his letters). They began:

1. Take out cabbage

2. Wash cabbage

He took the cabbage in hand, applied a healthy squirt of Fairy Liquid, and scrubbed the entire thing down. My dad told me this story, and said that he was so hungry, that he actually ate the meal.

There was nothing inherently wrong with my grandmother’s documentation, but it was wrong for the audience, which I suppose makes it as wrong as it could be. There is no neutral or ‘normal’ audience, and no set of fact which can be presumed.

We see the same problem with the best documentation out there - the Arch wiki. It might tell you everything you need to know, but it’s very little use for someone who earnestly wants to control their own computer, but doesn’t know how the thing works.

The Solution

No solution will work for everyone, so the closest thing we have to a general solution is one set of documentation for every group. As painful as that sounds, it’s less painful than someone looking up ‘how to start a service on Linux’, and reading some page about Pottering, because they don’t know what they should be reading.

We might also simplify things with some basic dependencies. When you try to install mupdf, most systems understand that you also need libfreeglut. However, look up hugo, and it won’t tell you what markdown it. A basic intro (and perhaps some general knowledge-standard for Unix) might have included the simple sentence ‘for this project, you will need to know markdown and basic web hosting’.