I'll definitely have to check out the rest of their 'compendium': https://www.destroyallsoftware.com/compendium
I'll definitely have to check out the rest of their 'compendium': https://www.destroyallsoftware.com/compendium
I've served the technical writing role a few times.
If it (your product) is hard to describe, you probably did it wrong. At the very least, keep trying until things make sense. Better mental models, metaphors, workflows, whatever.
I was once asked (by a school principle, former writing teacher) why software developers are such terrible writers. I replied that all the good software developers I know are also good writers. That if you can write an essay, you can also code. The problem is that most people are terrible writers, programmers included.
I will admit that writing is harder than programming. Because people are far more interesting, complicated, nuanced than computers.
Reading someone else's code is the closest thing we have to mind reading. More so than prose. IMHO.
Miscommunication and ambiguity is the norm. We all just have to accept that and keep trying.
This was revolutionary back in the days when most protocol specs were proprietary and designed to protect the priesthood (usually of a particular vendor)rather than facilitate interoperability. It's hard to imagine now, but one of the big reasons TCP/IP won was that it actually encouraged interoperability and interworkability. (Jan Stefferud drew a distinction between those two terms in this context...)
The corporate pricing could include a commitment to update some percentage of docs within 12 months of a relevant RFC being published or whatever.
Keeps purchasing happy, is a way for folks in the enterprise to get their employer to fund some resource and still gets it to mostly remain a labor of love.
I attend a conference that works that way. Essentially there are two conferences at the same time, with identical badges (no conference name on the badge itself), one of which costs about $800 and one of which costs about $3000 IIRC, if you buy all the special upgrades. Any company that pays the for the "corporate" conference gets listed as a sponsor as well :-).
[0]: http://poopy.life/
His explanations focus on the most important bits (which he has skillfully prioritized based on his expert knowledge) and avoid highly domain specific nomenclature i.e. he gives a thorough-yet-concise explanation in a way that a reasonably intelligent lay person can understand.
Does that make sense?
It broke programming down to its most fundamental and important building blocks without all the baggage of machine/operating system/application/dependency/etc specific stuff.
[1] https://www.youtube.com/watch?v=2Op3QLzMgSY&list=PL8FE88AA54...