8 ms·

Ask HN: Documentation before starting a software project?

How much up-front documentation do you write before starting a software project? Do you do any tradeoff studies or analysis, and if so, of what?

gabrtv 12y ago
I'm a big believer in "Readme driven development" [1]. It's critical you go through the exercise of 1) explaining what the software will do and 2) how it will be used with concrete examples. The value of this documentation will always outweigh the time spent writing it. [1]: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html http://tom.preston-werner.com/2010/08/23/readme-driven-devel...
Someone1234 12y ago
I find whiteboard and or Visio diagramming pretty useful (both high level, and more fine grain). However aside from in school I've never documented, designed, developed in the waterfall model style. I've never seen anyone else work that way either in "real life." Most places either officially use agile-style development or unofficially do (i.e. claim they use the waterfall model, but in reality are going back and updating the requirements/design throughout development). Something can be said for Unit Test-first development. However you really need to have good tooling, mocks, and so on before that is viable (otherwise you burn too much time getting even basic unit tests off the ground).
- supahfly_remix 12y ago
  What do you diagram on the whiteboard/Visio? Class hierarchies?
  - Someone1234 12y ago
    Sometimes. Sometimes a database hierarchy (if we're doing an API to a data source). Sometimes a UI concept. It really depends on the project and where the main complexity occurs.
loumf 12y ago
The minimum needed at each stage to get buy-in, inform, and help plan. For example: 1. At inception, a one-pager to make the business case and get funding/backing/ok/whatever. Audience: executives 2. Before starting, the end-user perspective on what is going to be done. Get feedback, use for sizing/scheduling. Audience: other departments 3. Before too much construction (after a proof-of-concept), an overview of the basic architecture and sketch of a plan. Audience: other developers.

How much up-front documentation do you write before starting a software project? Do you do any tradeoff studies or analysis, and if so, of what?

gabrtv 12y ago

I'm a big believer in "Readme driven development" [1]. It's critical you go through the exercise of 1) explaining what the software will do and 2) how it will be used with concrete examples. The value of this documentation will always outweigh the time spent writing it. [1]: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html http://tom.preston-werner.com/2010/08/23/readme-driven-devel...

Someone1234 12y ago

I find whiteboard and or Visio diagramming pretty useful (both high level, and more fine grain). However aside from in school I've never documented, designed, developed in the waterfall model style. I've never seen anyone else work that way either in "real life." Most places either officially use agile-style development or unofficially do (i.e. claim they use the waterfall model, but in reality are going back and updating the requirements/design throughout development). Something can be said for Unit Test-first development. However you really need to have good tooling, mocks, and so on before that is viable (otherwise you burn too much time getting even basic unit tests off the ground).

supahfly_remix 12y ago
What do you diagram on the whiteboard/Visio? Class hierarchies?
- Someone1234 12y ago
  Sometimes. Sometimes a database hierarchy (if we're doing an API to a data source). Sometimes a UI concept. It really depends on the project and where the main complexity occurs.

loumf 12y ago

The minimum needed at each stage to get buy-in, inform, and help plan. For example: 1. At inception, a one-pager to make the business case and get funding/backing/ok/whatever. Audience: executives 2. Before starting, the end-user perspective on what is going to be done. Get feedback, use for sizing/scheduling. Audience: other departments 3. Before too much construction (after a proof-of-concept), an overview of the basic architecture and sketch of a plan. Audience: other developers.