đž Archived View for splint.rs âş documentation.gmi captured on 2024-08-18 at 17:40:41. Gemini links have been rewritten to link to archived content
âŹ ď¸ Previous capture (2024-07-08)
-=-=-=-=-=-=-
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.
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â.