"So, if developers aren’t going to use Try Its, what harm is there for including them? They can just ignore them, right? Perhaps, but there’s more to it.

It takes up valuable screen real estate (the right corner above the fold). Writers need to optimize the developer experience, even to the point of minimizing eye movements. Make it easy to find details. That space could be used more productively.

We “should know” but we don’t. This segues into the real reason. It demonstrates that writers don’t know the developer experience. Let’s be blunt. We’re delivering documentation suites that have not been tested properly, calls that are unlikely to have been tested, and tools developers don’t use. Not understanding these issues is the fundamental reason writers also need developer experience. Writers simply can’t empathize with own audiences, which means we supplying developers with inadequate and incomplete tools and documentation. This is a real concern.

This is not a condemnation. Quite the opposite. API documentation writers need to empathize with developers. Writers do this by treating this as a craft, learn a little about development each day, and move slowly along the experience spectrum towards the developer’s end. Learn a language. It doesn’t matter which one. Java, JavaScript, to DOS batch commands, UNIX command line programming, Word macros, Python, or even AutoHotKey*. All of these have programming concepts and that’s what matters. Learn about them, which requires using an API guide, craft statements, and debug them is at the heart of the matter."

https://robertdelwood.medium.com/why-i-dont-like-try-it-f44112ed1b6d

#APIs #APIDocumentation #SoftwareDevelopment #TechnicalWriting