"The only goal of API documentation has to be for “great documentation.” I define that as documentation so clear so it defies misunderstanding. Why would it be anything else? While it sounds like a lofty goal, it’s easily obtainable and within everyone’s reach. It begins by thinking like a developer. API documentation writers have to move away from thinking like a technical writer.
When documenting strings, many writers just think about this as little more as characters within quotes, or as a combined set of characters. The following are two examples commonly documented for strings. In a moment, you’ll see how inadequate these really are."
https://robertdelwood.medium.com/the-truth-about-describing-strings-932c28bbde22
#APIDocumentation #APIs #TechnicalWriting #SoftwareDocumentation #SoftwareDevelopment #Programming
I define that as documentation so clear so it defies misunderstanding
This is why developers should have to work in support for a few years, like mandated military service. The experience would stop them from believing nonsense like being able to defy misunderstanding.
I had someone fuck up clicking a link yesterday. Twice.
