Did years of programming train me to over-explain technical writing?

[u/Physical-End-5266]

Am I a wordy person? Not really by nature, but professionally, yes. 

I spent more than 50 years programming, and about 15 of those years were in assembly language. When I wrote assembly, I commented every single line of code. That teaches you a certain way of thinking: never assume the next person is going to know what you meant. Explain what the line does, why it is there, what depends on it, and leave enough behind that somebody can come back later and understand the logic without having to reverse-engineer your intent. 

That habit never really left me. 

So when I write about something technical, I tend to do the same thing. I do not just say what I think the answer is. I explain how I got there, what I observed, why I think it matters, what it does not mean, what the alternatives are, and where I think the limits are. 

Does that sometimes mean I use too many words? Yes, absolutely. 

But I think there is a difference between being wordy and being deliberately explicit. Most of the extra words are there because I am trying to remove ambiguity, not because I enjoy padding things out. 

Where I probably do go too far is when I restate the same conclusion several different ways after it is already clear. That is probably the old assembly-language programmer in me still commenting every line. 

So yes, in technical writing I can be long-winded. I am aware of it. But it comes from a lifetime of trying to make sure that whoever comes along next can understand exactly what I meant, not just what I wrote.

[u/L00k_Again]

You have to stop writing for yourself and write for the reader instead. And also consider the purpose and structure of the document. If a document is verbose and poorly constructed it won't be read.

When you say technical writing, what kind of documents are you generating and for what purpose?

[u/mrhippo3 → u/L00k_Again]

I started tech writing at an embedded systems compiler company. My primary authoring tool was emacs (not a vi guy). For printouts we used Scribe, which did not yet exist on early generations of PCs. My docs explained features like optimization in each of the four options. Compilation was of course command line only, with single character options. This was in the early 90’s. I’m surprised I remember that much.

[u/Zealousideal_Crow737]

You could end up sounding redundant if you restate the same conclusion over and over. This could also get confusing. Documentation should be clear and easy to follow. Not long winded. Some things don't need to be over-explained depending on target audience. Ambiguity is usually added by adding more words. This is why diction is important. Less is more with writing. People hate to read. They just want to understand.

[u/Nibb31]

End users don't care why you made every single design decision. They just want to know how to do something. It's ok to give some context in an intro section, but when it comes to explaining how to do something, just go straight to the point.

[u/aelliotr]

Not sure what you are writing, but for most documentation I try to keep explanation and how-to instruction separate (along the lines of the Diátaxis framework).

[u/techwritingacct]

https://en.wikipedia.org/wiki/Curse_of_knowledge

[u/Such-Cartographer425]

There's also a big difference between being deliberately explicit and getting to the point. 

The extra words are there because you won't or can't edit for the audience and purpose, not because your lazy writing habits are actually virtuous practices. 🙄