3 ms·

Writing documentation up front is a good idea, but only if one treats it as the first iteration of the program with the expectation that the initial documentati

by diffxx 2y ago

Writing documentation up front is a good idea, but only if one treats it as the first iteration of the program with the expectation that the initial documentation may well be thrown out. The process of writing the documentation no doubt will help you organize the plan for writing the code. But there will also be things that the documentation does not capture or problems it does not foresee that emerge as the program is being written. The danger is that either you fail to update the documentation to account for the changes in the system that emerge in development or you only update parts of the documentation as you go which causes the documentation to become inconsistent and unreliable. A middle ground is write the documentation up front and then rewrite it after the system is done. The initial draft helps guide the design and the final version captures the full and complete essence of the finished program, which is nearly impossible to do up front.

charlie0 2y ago
This lines up perfectly with my use of the documentation. It really helps quite a lot to do it first, but as the implementation is underway, new scenarios come up and it's often a challenge to go back and update the docs. The new things also aren't something that derails the entire design. In the end, the docs are usually thrown away or transmuted into something useful for other departments.
bunderbunder 2y ago
Another nice benefit of doing it this way is that it allows the two sets of documentation to follow different formats and levels of detail. Which can ultimately be less total effort than trying to engineer a functional multitool.
6510 2y ago
> Writing documentation up front is a good idea, but only if one treats it as the first iteration of the program with the expectation that the initial documentation may well be thrown out. The process of writing the documentation no doubt will help you organize the plan for writing the code. But there will also be things that the documentation does not capture or problems it does not foresee that emerge as the program is being written. Everyone else is building all kinds of things from technical drawings. We could identify and describe what is so different about writing code which would make it clear what not to document or we can just suck it up, stop pretending our problems are special and closely mimic existing methods :) Making a construction drawing is hard but people are some how doing it, they make them for mind blowing size projects. Things definitely go wrong but no one says it is just the way things are. If changes are made there shall be new drawings. However, when it comes to renovation or repairs the process is often the opposite. Unless it is a boat, there if every brush of paint is meticulously documented it adds value in $$$. A friend told a funny story about construction workers building a large building across the street while they were debugging their code. First he joked about construction workers doing real work, then about how structured everything was and eventually about the building being finished while they still had countless bugs.
- Swizec 2y ago
  > Things definitely go wrong but no one says it is just the way things are. If changes are made there shall be new drawings. > then about how structured everything was and eventually about the building being finished while they still had countless bugs There is a famous story of the Hyatt Walkway Collapse where a change was made, was improperly documented, and caused a production bug that led to many deaths. Extreme example but production bugs in physical construction are extremely common. https://en.wikipedia.org/wiki/Hyatt_Regency_walkway_collapse https://en.wikipedia.org/wiki/Hyatt_Regency_walkway_collapse edit: Here's a whole paper looking into the effects of design errors in construction projects. This implies they're common enough to study. https://www.researchgate.net/publication/330701193_EFFECTS_OF_DESIGN_ERRORS_ON_CONSTRUCTION_PROJECTS https://www.researchgate.net/publication/330701193_EFFECTS_O... And here's some research that showed 10% to 25% of cost in construction goes towards fixing errors. https://getitright.uk.com/reports/call-to-action https://getitright.uk.com/reports/call-to-action
  - 6510 2y ago
    Construction has a much more mature building process, much of that is probably related to the cost of replacing things. We even get to cut and paste :) That last document seems like something that could be done in software development. Their list (starting with the worse) is dominated by mistakes pouring concrete. - Inadequate planning (from task through to project level) - Late design changes - Poorly communicated design information - Poor culture in relation to quality - Poorly coordinated and incorrect design information - Inadequate attention paid in the design to construction - Excessive commercial (financial and time) pressures - Poor interface management and design - Ineffective communication between team members - Inadequate supervisory skills For software we would have to gather the data similarly. Then you put it all into an LLM along with the employees previous assignments and code, pull the lever and the answers come out. Ah, yes. The aim should be to have pure information so that insurance companies can pick up the bill. In order to accomplish that the system should prevent the employer from meddling in the process. Working from home seems required to properly benchmark the employees.
4star3star 2y ago
The questionable reliability of documentation is the big problem, for sure. It would be nice to be able to collect metadata such as referral dates and even comments. If you visit the docs, tick a box that says, "I referred to this and it was accurate," or, "This needs to be updated," etc.
delusional 2y ago
>but only if one treats it as the first iteration of the program with the expectation that the initial documentation may well be thrown out. This point really hints at there being some other facotr at play. I agree that writing documentation first is fine, but in the same way writing some bad code is fine. I'd argue that the most important thing you can do to increase your chance of success is getting to the details as fast as possible. Do everything you can to get out of nebulous "big idea" mode and get into "we have this, what exactly are we changing about it" mode. If you write documentation or code doesn't matter.

by diffxx 2y ago

charlie0 2y ago

This lines up perfectly with my use of the documentation. It really helps quite a lot to do it first, but as the implementation is underway, new scenarios come up and it's often a challenge to go back and update the docs. The new things also aren't something that derails the entire design. In the end, the docs are usually thrown away or transmuted into something useful for other departments.

bunderbunder 2y ago

Another nice benefit of doing it this way is that it allows the two sets of documentation to follow different formats and levels of detail. Which can ultimately be less total effort than trying to engineer a functional multitool.

6510 2y ago

> Writing documentation up front is a good idea, but only if one treats it as the first iteration of the program with the expectation that the initial documentation may well be thrown out. The process of writing the documentation no doubt will help you organize the plan for writing the code. But there will also be things that the documentation does not capture or problems it does not foresee that emerge as the program is being written. Everyone else is building all kinds of things from technical drawings. We could identify and describe what is so different about writing code which would make it clear what not to document or we can just suck it up, stop pretending our problems are special and closely mimic existing methods :) Making a construction drawing is hard but people are some how doing it, they make them for mind blowing size projects. Things definitely go wrong but no one says it is just the way things are. If changes are made there shall be new drawings. However, when it comes to renovation or repairs the process is often the opposite. Unless it is a boat, there if every brush of paint is meticulously documented it adds value in $$$. A friend told a funny story about construction workers building a large building across the street while they were debugging their code. First he joked about construction workers doing real work, then about how structured everything was and eventually about the building being finished while they still had countless bugs.

Swizec 2y ago
> Things definitely go wrong but no one says it is just the way things are. If changes are made there shall be new drawings. > then about how structured everything was and eventually about the building being finished while they still had countless bugs There is a famous story of the Hyatt Walkway Collapse where a change was made, was improperly documented, and caused a production bug that led to many deaths. Extreme example but production bugs in physical construction are extremely common. https://en.wikipedia.org/wiki/Hyatt_Regency_walkway_collapse https://en.wikipedia.org/wiki/Hyatt_Regency_walkway_collapse edit: Here's a whole paper looking into the effects of design errors in construction projects. This implies they're common enough to study. https://www.researchgate.net/publication/330701193_EFFECTS_OF_DESIGN_ERRORS_ON_CONSTRUCTION_PROJECTS https://www.researchgate.net/publication/330701193_EFFECTS_O... And here's some research that showed 10% to 25% of cost in construction goes towards fixing errors. https://getitright.uk.com/reports/call-to-action https://getitright.uk.com/reports/call-to-action
- 6510 2y ago
  Construction has a much more mature building process, much of that is probably related to the cost of replacing things. We even get to cut and paste :) That last document seems like something that could be done in software development. Their list (starting with the worse) is dominated by mistakes pouring concrete. - Inadequate planning (from task through to project level) - Late design changes - Poorly communicated design information - Poor culture in relation to quality - Poorly coordinated and incorrect design information - Inadequate attention paid in the design to construction - Excessive commercial (financial and time) pressures - Poor interface management and design - Ineffective communication between team members - Inadequate supervisory skills For software we would have to gather the data similarly. Then you put it all into an LLM along with the employees previous assignments and code, pull the lever and the answers come out. Ah, yes. The aim should be to have pure information so that insurance companies can pick up the bill. In order to accomplish that the system should prevent the employer from meddling in the process. Working from home seems required to properly benchmark the employees.

4star3star 2y ago

The questionable reliability of documentation is the big problem, for sure. It would be nice to be able to collect metadata such as referral dates and even comments. If you visit the docs, tick a box that says, "I referred to this and it was accurate," or, "This needs to be updated," etc.

delusional 2y ago

>but only if one treats it as the first iteration of the program with the expectation that the initial documentation may well be thrown out. This point really hints at there being some other facotr at play. I agree that writing documentation first is fine, but in the same way writing some bad code is fine. I'd argue that the most important thing you can do to increase your chance of success is getting to the details as fast as possible. Do everything you can to get out of nebulous "big idea" mode and get into "we have this, what exactly are we changing about it" mode. If you write documentation or code doesn't matter.