Hacker Newsnew | past | comments | ask | show | jobs | submitlogin
Ask HN: Documentation before starting a software project?
8 points by supahfly_remix on Feb 17, 2015 | hide | past | favorite | 5 comments
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?


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).


What do you diagram on the whiteboard/Visio? Class hierarchies?


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.


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-devel...


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.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: