5 ms·

So, in other words: write a specification document and then build. Isn't this what many reasonably run companies do anyway? There have been very few instances

So, in other words: write a specification document and then build. Isn't this what many reasonably run companies do anyway? There have been very few instances in my coding career where I've been asked to build something that didn't have a spec doc, design or some form of legwork done prior to implementation. A design I would argue is a form of documentation, visual documentation. The handful of situations where I've been asked to do something was a result of one boss in particular who was an ideas guy and would always come to me and ask me to build demos for ideas based on a few minutes of conversation.

bruce511 4y ago
In a team/large company context, yes - a spec gets made then some (usually someone else) gets to write the code. In a smaller context one, or two, people may be responsible for design and code. Assuming they have a good understanding of the problem space they may start with some practical things (like database design) then program, then document (if you're lucky) So, as with most things, context matters.
- DigitalSea 4y ago
  You are completely right. Context definitely matters. The smaller team angle isn't something I thought about when I wrote my comment.
- dgb23 4y ago
  If you work on client projects in a small team then a functional spec can help you keeping everything conceptual in one place and have a basis for discussion. It doesn’t have to be the most elaborate thing. A smaller project gets a few pages with some pictures, a more involved one has more explanation and database diagrams, a few stories and such. You do this work anyway, so why not write it down in a structured way? Pragmatic and simple but clear and neat. You’ll find that people do not tend to read every detail, but you can refer to the details when needed, which is very useful.
arinlen 4y ago
> Isn't this what many reasonably run companies do anyway? I love how the most basic of practices in any engineering field is depicted as a groundbreaking epiphany in the software industry.
- DocTomoe 4y ago
  Software Engineering is still in the stage of early industrialism - when James Watt built his steam engine, or Carl Benz built his car, they did not have specification documents. They tinkered and made it work, moving around assemblies until everything fit, then improved on the design. Essentially, they were doing some form of 'agile': small teams (to the point of only one), no specifications, high turnover. Today, this approach is unthinkable in mechanical engineering, because bad designs are lethal. The software engineering environment is special because when it started out, everyone thought of it as just another branch of engineering, so they applied standard industrial processes onto it - and that did not work well, what worked for building hydraulic presses did not translate well to writing software. SE needed to "learn" how to tinker and experiment on mid-sized projects first, and now they are in an early-industrial-age phase (and call it 'agile'). Eventually, SE will return to something more organized, something more reliable - after all, we are learning that bad design choices can be lethal. We are seeing the first steps today, trying to capture agility with frameworks, with dedicated test methodologies, ... Naturally, this will cause frustration with the tinkerers, and it will take time. And while some aspects will resemble mechanical engineering processes, some things will be completely new and untranslatable to other engineering disciplines.
  - rileyphone 4y ago
    We've been waiting for years for software to become something more organized and reliable. It will take a rethinking of the fundamentals to get there IMO, along the lines of Brad Cox's thinking in [0]. Object-oriented programming was a revelation for a period, but overhype and overselling has made it non grata to a lot of developers. Now we wonder, what the next iteration of progress will be? [0] https://www.researchgate.net/profile/Brad-Cox-2/publication/3246772_Planning_the_software_industrial_revolution/links/540f00220cf2df04e759dae8/Planning-the-software-industrial-revolution.pdf?origin=publication_detail https://www.researchgate.net/profile/Brad-Cox-2/publication/...
deleted 4y ago
[deleted]
ds_ 4y ago
Documentation (and press releases/FAQs) are usually for users. Specifications are for developers. The former can precede and help with forming the latter.
vintagedave 4y ago
> So, in other words: write a specification document and then build. I don't believe this is what the article is saying at all. I interpreted the headline that way, but the article seems to be saying to hav a goal upfront (written) and write docs along the way, also using the process of writing text as a way to clarify thinking. See comment: https://news.ycombinator.com/item?id=31751399 https://news.ycombinator.com/item?id=31751399

bruce511 4y ago

In a team/large company context, yes - a spec gets made then some (usually someone else) gets to write the code. In a smaller context one, or two, people may be responsible for design and code. Assuming they have a good understanding of the problem space they may start with some practical things (like database design) then program, then document (if you're lucky) So, as with most things, context matters.

DigitalSea 4y ago
You are completely right. Context definitely matters. The smaller team angle isn't something I thought about when I wrote my comment.
dgb23 4y ago
If you work on client projects in a small team then a functional spec can help you keeping everything conceptual in one place and have a basis for discussion. It doesn’t have to be the most elaborate thing. A smaller project gets a few pages with some pictures, a more involved one has more explanation and database diagrams, a few stories and such. You do this work anyway, so why not write it down in a structured way? Pragmatic and simple but clear and neat. You’ll find that people do not tend to read every detail, but you can refer to the details when needed, which is very useful.

arinlen 4y ago

> Isn't this what many reasonably run companies do anyway? I love how the most basic of practices in any engineering field is depicted as a groundbreaking epiphany in the software industry.

DocTomoe 4y ago
Software Engineering is still in the stage of early industrialism - when James Watt built his steam engine, or Carl Benz built his car, they did not have specification documents. They tinkered and made it work, moving around assemblies until everything fit, then improved on the design. Essentially, they were doing some form of 'agile': small teams (to the point of only one), no specifications, high turnover. Today, this approach is unthinkable in mechanical engineering, because bad designs are lethal. The software engineering environment is special because when it started out, everyone thought of it as just another branch of engineering, so they applied standard industrial processes onto it - and that did not work well, what worked for building hydraulic presses did not translate well to writing software. SE needed to "learn" how to tinker and experiment on mid-sized projects first, and now they are in an early-industrial-age phase (and call it 'agile'). Eventually, SE will return to something more organized, something more reliable - after all, we are learning that bad design choices can be lethal. We are seeing the first steps today, trying to capture agility with frameworks, with dedicated test methodologies, ... Naturally, this will cause frustration with the tinkerers, and it will take time. And while some aspects will resemble mechanical engineering processes, some things will be completely new and untranslatable to other engineering disciplines.
- rileyphone 4y ago
  We've been waiting for years for software to become something more organized and reliable. It will take a rethinking of the fundamentals to get there IMO, along the lines of Brad Cox's thinking in [0]. Object-oriented programming was a revelation for a period, but overhype and overselling has made it non grata to a lot of developers. Now we wonder, what the next iteration of progress will be? [0] https://www.researchgate.net/profile/Brad-Cox-2/publication/3246772_Planning_the_software_industrial_revolution/links/540f00220cf2df04e759dae8/Planning-the-software-industrial-revolution.pdf?origin=publication_detail https://www.researchgate.net/profile/Brad-Cox-2/publication/...

deleted 4y ago

[deleted]

ds_ 4y ago

Documentation (and press releases/FAQs) are usually for users. Specifications are for developers. The former can precede and help with forming the latter.

vintagedave 4y ago

> So, in other words: write a specification document and then build. I don't believe this is what the article is saying at all. I interpreted the headline that way, but the article seems to be saying to hav a goal upfront (written) and write docs along the way, also using the process of writing text as a way to clarify thinking. See comment: https://news.ycombinator.com/item?id=31751399 https://news.ycombinator.com/item?id=31751399