Look, computers are like idiot savants - incredibly fast and capable of doing all sorts of things with mindless determination, but without a shred of common sense - so when you’re programming you have to literally explain everything including what for you is obvious and there is a whole class of bugs (around corner cases and boundary conditions) related to the programmers not explaining absolutelly everything and forgetting some really rare or unusual situations.
For documentation purposes one should assume that at least some users are like computers, without the savant part.
I write mine with a simple mindset: “imagine we go outside with a net, catch a random person off the street, sit them at the PC and tell them to do X. Will they manage, following this documentation?”
I also number every step (even if they’re stupidly simple and could technically be jumbled into a single sentence), so that when a user calls me asking for help with something documented, all I need to do is ask them “at which step of the instructions are you encountering the problem”, and then they hang up because they never read the instructions in the first place. Saves a lot of hassle!
I have never put it into words like that, more like “make zero assumptions”.
I suppose that being overly thorough can make documentation prone to becoming tedious (unless cares is taken to not talk down to the reader) or too tightly coupled (incurring the need to be updated more often as details of the process change).
How do you usually deal with that aspect? What I do is to make the documentation easily skimmable (for advanced readers) and just accept the need for rework.
How do you usually deal with that aspect? What I do is to make the documentation easily skimmable (for advanced readers) and just accept the need for rework.
Confluence’s “Expand” element. Make everything into an easy to read task-list, but if more details are necessary, just expand a step and get an “idiot proof” description. Bookstack allows that as well, even better, because you can nest them (Confluence had that up until they “updated” the editor and killed half the features).
EDIT: “Include Page” in Confluence also works wonders here. For example, I have an article describing how to RDP to our AD server. In all articles that describe a process that needs to be done on the AD server, I just include that page. If any connection details change, I just edit the original article and the changes immediately propagate to all the other instances.
Look, computers are like idiot savants - incredibly fast and capable of doing all sorts of things with mindless determination, but without a shred of common sense - so when you’re programming you have to literally explain everything including what for you is obvious and there is a whole class of bugs (around corner cases and boundary conditions) related to the programmers not explaining absolutelly everything and forgetting some really rare or unusual situations.
For documentation purposes one should assume that at least some users are like computers, without the savant part.
I write mine with a simple mindset: “imagine we go outside with a net, catch a random person off the street, sit them at the PC and tell them to do X. Will they manage, following this documentation?”
I also number every step (even if they’re stupidly simple and could technically be jumbled into a single sentence), so that when a user calls me asking for help with something documented, all I need to do is ask them “at which step of the instructions are you encountering the problem”, and then they hang up because they never read the instructions in the first place. Saves a lot of hassle!
I have never put it into words like that, more like “make zero assumptions”.
I suppose that being overly thorough can make documentation prone to becoming tedious (unless cares is taken to not talk down to the reader) or too tightly coupled (incurring the need to be updated more often as details of the process change).
How do you usually deal with that aspect? What I do is to make the documentation easily skimmable (for advanced readers) and just accept the need for rework.
Confluence’s “Expand” element. Make everything into an easy to read task-list, but if more details are necessary, just expand a step and get an “idiot proof” description. Bookstack allows that as well, even better, because you can nest them (Confluence had that up until they “updated” the editor and killed half the features).
EDIT: “Include Page” in Confluence also works wonders here. For example, I have an article describing how to RDP to our AD server. In all articles that describe a process that needs to be done on the AD server, I just include that page. If any connection details change, I just edit the original article and the changes immediately propagate to all the other instances.
I really like the social engineering element of your documentation strategy!
You’re brutal. You’re not wrong tho.