"In the case of tech writing, thinking that you’re creating docs when what you’re doing is dumping words into a file is particularly wrong, because docs have a moral obligation to solve needs.
(...)
Creating a tutorial aimed at beginners without knowing what the beginner thinks is an empty gesture. Consider any such tutorial in the wild: If instead of following the inviting form of a tutorial it had been written like an entry from a dev diary, it would have offered a more sincere experience, one that would have signaled to the reader that this content wasn’t really for them after all. You can deal with the curse of knowledge either by becoming a beginner, or by not pretending you’re talking to one (that’s why someone like John Carmack is honest).

Unfortunately, organizations often don’t care about the quality of their content (performative or not), and while they might have perceived the signs that they need tech writers, they might still ask folks to create documentation to fulfill a goal or satisfy their particular Definition of Done. Sometimes we can’t escape the script that’s being forced onto ourselves, but, while the fake author in Annie’s post has a cruel side in that it’s utterly devoid of empathy, you can choose not to be like it. This is the duty of tech writers: to uphold clarity and defend user comprehension in all situations where tech comms risk becoming faux."

passo.uno/documentation-theate…

#TechnicalWriting #Documentation #SoftwareDocumentation #DocumentationTheater #SoftwareDevelopment #Tutorials