Obviously…

I’ve been reading a lot of technical documents recently and it starts to coagulate in my mind; in some ways I am getting to understand the topic better but in others, I am starting to realise how much I don’t know and need to know. It’s exciting and frustrating at the same time.

To add to that, these documents also are not written for beginners to learn and understand the concepts. They are mostly written for users to implement them. References are thrown here and there, where if you’re new, you’ll be avalanched by them. Most annoying of all is within an explanation, there’s a contradicting statement or exclusion that starts with the phrase “obviously”, although to me, after rereading it multiple times, nothing seemed obvious. I can’t think of a reason for the statement, and it obviously made me feel stupid.

And I am no alone in this. I have talked this out with colleagues and they agreed. A person writing a technical document would have understood the topic to be assigned or even started writing, hence their level of understanding is different. The explicit or implied reasons to a particular point are clear to them. It is obvious to them. It is however not obvious to others.

Obviously this is hard to imagine from the writers perspective. See, I just did something there. Anyways my takeaway is that when writing technical stuff, I need to avoid using subjective adverbs such as “obviously”, as it doesn’t help in reading nor understanding the text.

Thank you for reading.