[canada_dry]

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

[specialist]

"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]

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 - 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...)

[C1sc0cat]

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

[readingnews]

Agree, and love that guys domain name.

[thijsvandien]

I love it too. Sadly, not to long ago he considered changing it because it makes their materials a hard sell to enterprises.

[gumby]

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]

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/

[coreypreston]

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

[canada_dry]

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]

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=PL8FE88AA54...

[madhadron]

The Feynman lectures are also not useful to learn physics from, so you may want to avoid that as a standard.

[coreypreston]

That does, thanks for sharing.