It's a sticky wicket.
Writing technical content is unlike writing for any other genre. In a technical article, the hero of the story is the reader and author's job is to help the hero prevail against any odds. The problem is - sometimes the odds are stacked against us all.
There's an intuitive balance writers face that pits clarity against comprehension. If you make a piece too easy, some note that your content is "not real world enough". At the same time, if an article attempts to better reflect the real world, readers are often left asking themselves questions like:
- What is going on here?
- Do I really need to know all this?
- How do I just do X?
Is there a solution? Yes and no.
While there's no set answer, skilled writers who attempt to anticipate a reader's needs can even the scales. This hard-earned skill is much easier said than done. As a writer, the more you empathize with the daily life of those reading your content, the better you'll become at being both clear AND comprehensive.
So the next time you read an article, watch an online course, or read book and find yourself thinking the concepts are too "rudimentary to be useful" or "too complex to be understandable" - have mercy - your author is under a curse.