First and foremost, who are you talking to?
Second, keep it plain and succinct. No convolution. No wordwalls.
Third. Use pictures and diagrams whenever possible.
(From my father, a technical writer of some renown.)
The Surprising Power of Documentation
111–120 of 153 posts
Re: The Surprising Power of Documentation
#112Earlier quoted context omitted.
I am a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code. get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it ch…
Most of what you described as needing documentation could be expressed as code (mixing multiple languages here to express the point more clearly) const fn get_outer_height() -> Result > - `const` makes it clear this doesn't mutate - the function name says exactly what it does - The return type makes it clear it can return an error - The return value is typed in a way that makes it clear what the ownership is Throw in…
You are absolutely right, and one should prefer languages that can give such guarantees wherever possible.
But often one doesn't have a choice. People still write software in inferior languages such as Javascript or Python, where you cannot even be sure about a return or parameter data type.
Re: The Surprising Power of Documentation
#113I can't stress this enough. Know your audience and tailor your documentation to them. You should write three types of documentation. One for users, one for admins and one about architecture. User docs are simple. How do I use it. What are the API calls, etc. Admin docs are about how to install/break-fix/troubleshoot issues that are beyond user interaction. Architecture is how the system is constructed, why certain te…
Surfing close to Robert Horn's Information Mapping. Which is a useful construct, but it's a dangerous idea to think that content information types just sort of live . . out there, somewhere. Content typing will always be context - dependent, which, well, can boil down to "know your audience". But the content types aren't General Truth, they do need audience to be defined, which is where I disagree with the DITA folks.
Re: The Surprising Power of Documentation
#114Earlier quoted context omitted.
I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically. Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice. In my…
This is API reference documentation. What you're missing is conceptual documentation and use case examples. Conceptual documentation, the big picture, is important to convey the mental model implemented by an API. In applications, you can generally infer it from using the app, but it's not always easy, and it's indirect. Use case examples string together multiple APIs, multiple domain objects, to achieve a high level…
I often call this narrative documentation. It's the antidote to Chesterton's Fence and explains the thinking of the programmer who created the thing. How did that programmer expect people to use their tool.
Re: The Surprising Power of Documentation
#115The thing that seems to come out of all these conversations is to treat documentation as UI/UX. Maybe the problem is that it is treated as a secondary activity for developers, when it should be treated as a primary activity for writers. We don't expect developers to be good at graphic design and even UI/UX design. In fact we should expect them to be terrible at it. A developer looks at the product from the inside, he…
That angle is very good.
To me what's missing in many of these discussions is the cost/result calculation, how much effect is expected from "documentation". Thinking of it as an UX/UI could help put it more in terms of what time is spend by which user to achieve which specific task.
If specific use cases can be described, what needs to be written down becomes a lot more obvious and it can be done way more efficiently than just blindly "documenting" a system.
Re: The Surprising Power of Documentation
#116I often find that trying to document code or a product forces me to rethink how I wrote it. Sometimes it's easier to change the code to make the concept simple to grok, then to write the documentation for the hard to grok concept. This is a very good thing.
Companies in general should do much more writing. Writing forces you to think in ways that coding doesn't. For me it's much easier to spot a poorly thought out argument then a bug in code (not a 1 for 1 comparison).
Re: The Surprising Power of Documentation
#117Earlier quoted context omitted.
What would you do? Accept that it's a big job and just get on with it. Sometimes we just have to do hard things. Putting it off or looking for a shortcut doesn't always work. I'd also spend a couple of months seeing how much of the documentation production I can automate though. That's a small investment in a 700 day project.
Yeah. There's this quote I love: > If you have a mountain of shit to move, how much time should you spend looking for a bigger shovel? There's no obviously correct answer - it must depend on the size of the mountain, the availability of large shovels, how quickly you have to move it etc. But the answer absolutely cannot be 100% of your time. At some point you have to shovel some shit. From https://www.scattered-thoug…
The corollary is also important. If you are writing code you should want it to solve a problem, and for it to be the chosen solution regularly. Make sure people with the problem you are solving know that your solution solves their problem, and how it solves their problem. That's the point of documentation.
Re: The Surprising Power of Documentation
#118Personally I think at the age of LLM lots of up-to-date documentation will be those superpowers that will boost some companies to whole new level.
Is it naive to assume that we could have bots actually read the code and come up with an "understanding" of what the code does instead of the metadata written by a human for humans on the side ?
Re: The Surprising Power of Documentation
#119Earlier quoted context omitted.
I admit, I rarely read documentation of anything, since I have no clue whether to trust it, so I will usually try to just follow my logical thought process of figuring out the solution or by trial and error. This also makes me bad myself at documentation, because if I don't use it I also feel internally that no one would read what I write in the first place also. Out of responsibility I will try to document shared th…
> I rarely read documentation of anything, since I have no clue whether to trust it There's another big issue with documentation; it's often a write-and-forget thing. I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified.
> I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified.
I'm not convinced this would work. Such a person wouldn't have time to be a subject matter expert at anything other than the documentation tools. They wouldn't understand what they were writing about.
Re: The Surprising Power of Documentation
#120Earlier quoted context omitted.
> You should write three types of documentation. One for users, one for admins and one about architecture. I use an airplane analogy (different order than your three above): 1. "Congratulations on purchasing your 747" 2. "This is how you replace the auxiliary power unit" 3. "This is how you survive the engine catching fire"
1 is not documenting anything, and both 1 and 3 are meant for pilots? Who are the "users" in this analogy?
On the contrary, 1 would be a "quickstart guide", a "welcome pack", or even just a "The first thing that you need to do to your new washing machine/jet aircraft is take the restraining bolts, used for immobilizing it during transport, off."