I've been spending a lot of time thinking about documentation, writing documentation, and creating a system called documentation.js.

is hitting it from one specific angle: API Docs. this sort of information lies at the concrete and technical end of the spectrum: while it can include lots of natural-language instructions, it is structured primarily from the view of the code.

manual for software: it's concerned with definition as much as explanation.

library authors will only write manual documentation, and a lot of people only write examples, or sometimes no docmentation at all. Documentation is as much a cultural issue as a technical one.

informed my decision to pour lots of time into documentation.js, both in terms of personal experience and also the changing way how the JavaScript community thinks.

the rise of Abstract Syntax Trees and good parsers for JavaScript is the single coolest thing I've seen in the last year.

documentation. It's a lot to write, right? But in a lot of ways, it's reiterating what the code already says. Here's the code that goes under it.

no matter how much you use its flexibility in regards to types, JavaScript still has them, and they matter. Polymorphic methods perform differently, and type coercion is really only sometimes the intent of someone who provides a string where you need a number.

is still kind of like a distant glint of light in another dimension saying 'what if writing code was not basically just writing text'. It's by no means as magic as visual coding or really trendy at all, but you really have to think about how many times you flip from your text editor to a README on GitHub in Chrome, and think about what could be.