3 ms·

Given that the article is focusing on designing and developing APIs, I'd argue that, done correctly, documentation is a prototype. It's functionally equivalent

Given that the article is focusing on designing and developing APIs, I'd argue that, done correctly, documentation is a prototype. It's functionally equivalent to paper prototypes and low-fi mockups in UI design. The thing that makes these kinds of artifacts so nice compared to just diving straight into cutting code (specifically implementation code - see my comment elsewhere on walking skeletons) is that they're cheaper to build and easier to throw away. Which lets you iterate more rapidly in the earlier stages of the project, with less risk of accidentally anchoring yourself to decisions that get made before you have sufficient information to support a firm decision. That's also arguably where the various design and documentation tools and techniques you listed fail. I haven't used all of them in anger, but at least by appearances they're all relatively heavyweight and expensive things that are generally ill-suited to lightweight early planning in anything short of a situation where you're dealing with a CMMI requirement.

javier_e06 2y ago
I agree the API that is the API is done correctly, it provides honest guidance. Once upon a time when 3G mobility was all the rave I was with a company named Lucent which was vying for a contract with Japanese NTT Docomo. The job: Provide BTS (Base Transceiver Stations) for their brand new network. Hardware and software. Their API documentation was an Excel Spreadsheet with c function call names, around 300. Column 1, the function name, column 2 the expected parameters in byt form, the return values in byte form and last column..the maximum time limit to return the call in milliseconds. The possible error codes (lots and lots of error codes) The API was also shared with Hitachi which was the competition. The API read like a Tax Form but the expectations where so well understood. Down to the bare metal.

javier_e06 2y ago

I agree the API that is the API is done correctly, it provides honest guidance. Once upon a time when 3G mobility was all the rave I was with a company named Lucent which was vying for a contract with Japanese NTT Docomo. The job: Provide BTS (Base Transceiver Stations) for their brand new network. Hardware and software. Their API documentation was an Excel Spreadsheet with c function call names, around 300. Column 1, the function name, column 2 the expected parameters in byt form, the return values in byte form and last column..the maximum time limit to return the call in milliseconds. The possible error codes (lots and lots of error codes) The API was also shared with Hitachi which was the competition. The API read like a Tax Form but the expectations where so well understood. Down to the bare metal.