Frustrated by Magento? Then you’ll love
I’m working my way through the TypeScript manual and pleasantly surprised to find really good tech writing. So far it’s clearly written and follows the “introduce a concept, here’s some code to backup that concept, talk about the concept again to reenforce” pattern I prefer in my own writing. The tone also does a delightful job of hiding most, but not all, of the TypeScript team’s eye rolling at some of the less robust parts of according-to-spec javascript.
It also touches on two personal points in my own career — back in 2006 I did a short contract stint at Microsoft before deciding I wanted to move back to Portland. That job was the first time I saw (and understood) people using javascript to build their own programming languages. I wouldn’t be surprised if some of the internal-ajax frameworks we were using then helped influence the internal development of TypeScript. (I also wouldn’t be surprised if that wasn’t true — the way things happen in big companies are usually non-obvious)
The other point is this document on modern javascript’s support for block scope. Most of my early programming was in languages without block scope, or where the curriculum specifically avoided discussing block scope in order to simply the teaching. When I started trying to do more than just hack together perl 4 scripts to make a website work I remember not even realizing block scope was a thing, and then struggling with things like perl’s my keyword because online learning was frustratingly cryptic back in those early days.
A document like the TypeScript manual’s Variable Declarations would have saved me a bunch of time. It’s not for beginners, exactly, but what’s written about scope is clear and relates directly to the code samples on display. i.e. there’s enough there for a smart motivated person to figure this out, vs. a lot of online tech writing that’s more about showing off what a person knows.