5 ms·

With the current state of generally terrible technical writing and my ever decreasing attention span it's bloody refreshing to read a concise and well written e

With the current state of generally terrible technical writing and my ever decreasing attention span it's bloody refreshing to read a concise and well written explanation of a highly technical subject! I'll definitely have to check out the rest of their 'compendium': https://www.destroyallsoftware.com/compendium https://www.destroyallsoftware.com/compendium

specialist 8y ago
"current state of generally terrible technical writing" 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.
- dublin 8y ago
  Not only that, the very idea of clear, literate explanations is really a core part of the entire Internet ethos, heavily influenced by UNIX. (Read http://theody.net/elements.html http://theody.net/elements.html - you'll be glad you did...) 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...)
coreypreston 8y ago
What do you see as an issue in technical writing, if anything past not concise or well written?
- canada_dry 8y ago
  I suppose it boils down to why the Feynman lectures are generally considered a gold standard in technical presentations. 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?
  - dmix 8y ago
    Agreed. This is also why I adore the SICP lectures from the 1980s [1] (and the book in general). 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=PL8FE88AA54363BC46 https://www.youtube.com/watch?v=2Op3QLzMgSY&list=PL8FE88AA54...
  - coreypreston 8y ago
    That does, thanks for sharing.
  - madhadron 8y ago
    The Feynman lectures are also not useful to learn physics from, so you may want to avoid that as a standard.
readingnews 8y ago
Agree, and love that guys domain name.
- thijsvandien 8y ago
  I love it too. Sadly, not to long ago he considered changing it because it makes their materials a hard sell to enterprises.
  - gumby 8y ago
    Some people have a "normal" site with "normal" pricing and an "enterprise" site with different formatting, pricing, etc (for example it could have a search box, even if all the searching is just a google search anyway). 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 :-).
    - fgandiya 8y ago
      There's this service [0] which is designed to set up quick WordPress installs for demos. The free tier uses the domain poopy.life and if you want to get a more professional domain to show off to clients, you pay extra. [0]: http://poopy.life/ http://poopy.life/
C1sc0cat 8y ago
When I was doing my CCNA the cisco press books where well written and went from first principals.

specialist 8y ago

"current state of generally terrible technical writing" 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.

dublin 8y ago
Not only that, the very idea of clear, literate explanations is really a core part of the entire Internet ethos, heavily influenced by UNIX. (Read http://theody.net/elements.html http://theody.net/elements.html - you'll be glad you did...) 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...)

coreypreston 8y ago

What do you see as an issue in technical writing, if anything past not concise or well written?

canada_dry 8y ago
I suppose it boils down to why the Feynman lectures are generally considered a gold standard in technical presentations. 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?
- dmix 8y ago
  Agreed. This is also why I adore the SICP lectures from the 1980s [1] (and the book in general). 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=PL8FE88AA54363BC46 https://www.youtube.com/watch?v=2Op3QLzMgSY&list=PL8FE88AA54...
- coreypreston 8y ago
  That does, thanks for sharing.
- madhadron 8y ago
  The Feynman lectures are also not useful to learn physics from, so you may want to avoid that as a standard.

readingnews 8y ago

Agree, and love that guys domain name.

thijsvandien 8y ago
I love it too. Sadly, not to long ago he considered changing it because it makes their materials a hard sell to enterprises.
- gumby 8y ago
  Some people have a "normal" site with "normal" pricing and an "enterprise" site with different formatting, pricing, etc (for example it could have a search box, even if all the searching is just a google search anyway). 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 :-).
  - fgandiya 8y ago
    There's this service [0] which is designed to set up quick WordPress installs for demos. The free tier uses the domain poopy.life and if you want to get a more professional domain to show off to clients, you pay extra. [0]: http://poopy.life/ http://poopy.life/

C1sc0cat 8y ago

When I was doing my CCNA the cisco press books where well written and went from first principals.