I like to write specs for humans.

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!

Gotta change with the times. 😀

PS: This should probably be filed under Rules for standards-makers.