4 ms·

Nobody's business was ever ruined because of bad documentation, sadly. Literate programming is an interesting idea from academia, but in the engineering enviro

Nobody's business was ever ruined because of bad documentation, sadly. Literate programming is an interesting idea from academia, but in the engineering environment of most startups it's a waste of time. Our program sources are annoying byproducts of a business, not something of value unto themselves.

Retra 11y ago
Just because it doesn't make you money doesn't mean it has no value.
- angersock 11y ago
  There is no engineering without dollar signs in the equation. I didn't say it had no value in general, just in a particular context.
tikhonj 11y ago
Nobody's business was ever obviously, directly ruined because of bad documentation, and so nobody was ever blamed for it or fired over it.
jlg23 11y ago
> Nobody's business was ever ruined because of bad documentation, sadly. I've seen quite a few startups fail because they had a smart, but completely undocumented code base. Then the smart programmers leave and who is left cannot handle the code and new hires take too long to get into it. Then funding runs out and the apparent lack of progress ensures that nobody wants to put more money into the company. > Literate programming is an interesting idea from academia, but in the engineering environment of most startups it's a waste of time. Amazingly, we're actually getting back to something that resembles literate programming - via TDD. Instead of asking for a proper spec, we now ask for test definitions that the code must pass. Those can even be written in something that is pretty close to natural language (cucumber etc) so that management can write them. Then we spend time to make the test framework understand all those pseudo-natural-language test definitions and then we finally write the code. Is that really faster? Or are we just missing the tools that would allow us to tie a natural language specification to code?
- copperx 11y ago
  > pretty close to natural language (cucumber etc) so that management can write them This sounds so familiar ...
  - douche 11y ago
    What a jokester! Management doing work? Then the engineers get to program in a less-powerful, more cumbersome language.
ken47 11y ago
That assertion seems arbitrary and unprovable.
artmageddon 11y ago
> Nobody's business was ever ruined because of bad documentation, sadly. Maybe not ruined, but certainly severely hampered. I worked for several months with an original author of a 1M LOC application, and he was let go because the company was too cheap to re-up his contract. The documentation in that time was barely passable and it took many months of tweaking and breaking things just to get back to the point of becoming productive again. No one had a well-documented procedure on how to even compile the code until I decided to set my tasks aside(to my own schedule's detriment) so I could document all the steps and dependencies along the way. Luckily for them the company was well established and could afford the wait, others may not have that luxury.

Retra 11y ago

Just because it doesn't make you money doesn't mean it has no value.

angersock 11y ago
There is no engineering without dollar signs in the equation. I didn't say it had no value in general, just in a particular context.

tikhonj 11y ago

Nobody's business was ever obviously, directly ruined because of bad documentation, and so nobody was ever blamed for it or fired over it.

jlg23 11y ago

> Nobody's business was ever ruined because of bad documentation, sadly. I've seen quite a few startups fail because they had a smart, but completely undocumented code base. Then the smart programmers leave and who is left cannot handle the code and new hires take too long to get into it. Then funding runs out and the apparent lack of progress ensures that nobody wants to put more money into the company. > Literate programming is an interesting idea from academia, but in the engineering environment of most startups it's a waste of time. Amazingly, we're actually getting back to something that resembles literate programming - via TDD. Instead of asking for a proper spec, we now ask for test definitions that the code must pass. Those can even be written in something that is pretty close to natural language (cucumber etc) so that management can write them. Then we spend time to make the test framework understand all those pseudo-natural-language test definitions and then we finally write the code. Is that really faster? Or are we just missing the tools that would allow us to tie a natural language specification to code?

copperx 11y ago
> pretty close to natural language (cucumber etc) so that management can write them This sounds so familiar ...
- douche 11y ago
  What a jokester! Management doing work? Then the engineers get to program in a less-powerful, more cumbersome language.

ken47 11y ago

That assertion seems arbitrary and unprovable.

artmageddon 11y ago

> Nobody's business was ever ruined because of bad documentation, sadly. Maybe not ruined, but certainly severely hampered. I worked for several months with an original author of a 1M LOC application, and he was let go because the company was too cheap to re-up his contract. The documentation in that time was barely passable and it took many months of tweaking and breaking things just to get back to the point of becoming productive again. No one had a well-documented procedure on how to even compile the code until I decided to set my tasks aside(to my own schedule's detriment) so I could document all the steps and dependencies along the way. Luckily for them the company was well established and could afford the wait, others may not have that luxury.