4 ms·

I have lived through all: Rational Rose UML RequistePro. Doors. Just plain prototype something through many iterations until is good then document. Doxygen Al

I have lived through all: Rational Rose UML RequistePro. Doors. Just plain prototype something through many iterations until is good then document. Doxygen All of the above except the prototyping a waste of resources more or less. If I had my software shop (which I don't) I would expect a software module to come with a README.md Which a brief explanation of what is is and no more than 3 step instruction for a reader to see the software module running and doing something useful.

bunderbunder 2y ago
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.
alganet 2y ago
> Just plain prototype something through many iterations until is good then document This is always the best. Iterative prototyping gives you continuous hindsight over design and implementation, _nothing_ beats that. Unless you're doing something trivial in which hindsight would only serve as temptation for yak-shaving. Then it's not so good. Unless you don't have deadlines, then it's good again.

bunderbunder 2y ago

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.

alganet 2y ago

> Just plain prototype something through many iterations until is good then document This is always the best. Iterative prototyping gives you continuous hindsight over design and implementation, _nothing_ beats that. Unless you're doing something trivial in which hindsight would only serve as temptation for yak-shaving. Then it's not so good. Unless you don't have deadlines, then it's good again.