

Ask HN: Documentation before starting a software project? - supahfly_remix

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?
======
Someone1234
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
What do you diagram on the whiteboard/Visio? Class hierarchies?

~~~
Someone1234
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.

------
gabrtv
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...](http://tom.preston-werner.com/2010/08/23/readme-driven-
development.html)

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

