| ▲ | theodpHN 5 hours ago | |
Tech documentation has been kind of a three-decade race to the bottom, with some ups and downs along the way. From vendor documentation in the 70's to Windows Help in the 90s to the rise of tech books incl. O'Reilly to fill the gap, to PDF and Internet document, and now to often lacking-in-detail Javadocs, Python docs, API interface, API docs, event/parameter lists, and GitHub README files that are passed off as documentation today, often with no detail, use examples, illustrations, or though-through overall structure and organization. In addition to the obvious negative effect on learning curves, I'd argue this dearth of "long-form documentation" has a negative impact on programming language and app development, as well as software usability in general (isn't CONTROL+COMMAND+SHIFT+3 for a MAC screen capture intuitive?).. AI has become the new "teacher of record" to fill this documentation void, but it's very individualized and narrowly focused. There's no longer a shared mental model, where everyone has read the same books and are working somewhat off the same page. Ironically, it's probably never been easier to write a good tech book, but there's likely zero money in it and the search and AI giants are likely to hover it up and start serving snippets of it up for free before you see a dime, making people very unlikely to buy your book, even if you've written a technical masterpiece! | ||