I write technical documentation and training materials as part of my job, and the state of most open source documentation makes me want to stab people with an ice pick.
Do you have any tips for writing professional documentation? I want to do some for my workplace but it’s hard to know where to start, how to arrange it, etc
Over my career, it’s sad to see how the technical communications groups are the first to get cut because “developers should document their own code”. No, most can’t. Also, the lack of good documentation leads to churn in other areas. It’s difficult to measure it, but for those in the know, it’s painfully obvious.
Yes. Here: "1.You aren’t writing an SOP for smart or even capable people., every. Single. Person. Needs their hand held all the way through every step regardless of technical skill. "
“2.if you didnt state it needed to be done in the SOP, it will not be done when the end user follows the SOP”
“3.MAKE someone else run through your SOP without you being involved. If they can successfully achieve what they needed using your SOP > congrats. If not > fix the errors that brought you to this mess.”
“4. Everyone is fucking stupid, be clear, and verbose.” We’re talking about where the start menu is, clicking on the “OK” for prompts, how to spell and type things out.
Change my given values per SOP and what it’s for. But those are my main tenants.
In elemental school we had to write instructions on how to make a pb&j sandwich. The teacher then acted out your instructions literally, without adding or removing a step. I don’t think there was a single sandwich made that day.
Excellent notes. If I could add anything it would be on number 4 – just. add. imagery. For the love of your chosen deity, learn the shortcut for a screenshot on your OS. Use it like it’s astro glide and you’re trying to get a Cadillac into a dog house.
The little red circles or arrows you add in your chosen editing software will do more to convey a point than writing a paragraph on how to get to the right menu.
I write technical documentation and training materials as part of my job, and the state of most open source documentation makes me want to stab people with an ice pick.
Do you have any tips for writing professional documentation? I want to do some for my workplace but it’s hard to know where to start, how to arrange it, etc
You’re doing God’s work!
Over my career, it’s sad to see how the technical communications groups are the first to get cut because “developers should document their own code”. No, most can’t. Also, the lack of good documentation leads to churn in other areas. It’s difficult to measure it, but for those in the know, it’s painfully obvious.
Do you have some reading recommendations on how to write good documentation, e.g. readmes for end users?
Yes. Here: "1.You aren’t writing an SOP for smart or even capable people., every. Single. Person. Needs their hand held all the way through every step regardless of technical skill. "
“2.if you didnt state it needed to be done in the SOP, it will not be done when the end user follows the SOP”
“3.MAKE someone else run through your SOP without you being involved. If they can successfully achieve what they needed using your SOP > congrats. If not > fix the errors that brought you to this mess.”
“4. Everyone is fucking stupid, be clear, and verbose.” We’re talking about where the start menu is, clicking on the “OK” for prompts, how to spell and type things out.
Change my given values per SOP and what it’s for. But those are my main tenants.
In elemental school we had to write instructions on how to make a pb&j sandwich. The teacher then acted out your instructions literally, without adding or removing a step. I don’t think there was a single sandwich made that day.
Excellent notes. If I could add anything it would be on number 4 – just. add. imagery. For the love of your chosen deity, learn the shortcut for a screenshot on your OS. Use it like it’s astro glide and you’re trying to get a Cadillac into a dog house.
The little red circles or arrows you add in your chosen editing software will do more to convey a point than writing a paragraph on how to get to the right menu.
Absolutely! But I use markdown / Obsidian for my SOPs so images are kinda obnoxious to format. But yes!