Imho too many specs are organized the way a computer would want them, the way software is organized. Establish basic vocabulary in layers then and assume the human reader will know how to put the pieces together to do things. Never answer questions a busy developer would have.#
Humans like it the other way around. Show me how to do X, Y and Z, the most common things people want to do with the API, and then later explain how the pieces fit together. The hello world approach.#
With the arrival of AI, computers can now read what humans read. So you should just write your specs for humans and it'll work fine for computers too!#
Last update: Wednesday June 28, 2023; 8:34 AM EDT.
You know those obnoxious sites that pop up dialogs when they think you're about to leave, asking you to subscribe to their email newsletter? Well that won't do for Scripting News readers who are a discerning lot, very loyal, but that wouldn't last long if I did rude stuff like that. So here I am at the bottom of the page quietly encouraging you to sign up for the nightly email. It's got everything from the previous day on Scripting, plus the contents of the linkblog and who knows what else we'll get in there. People really love it. I wish I had done it sooner. And every email has an unsub link so if you want to get out, you can, easily -- no questions asked, and no follow-ups. Go ahead and do it, you won't be sorry! :-)