views:

113

answers:

4

I've been tasked to write alot of documentation recently. I know it's the kind of thing some developer's probably cringe at but I don't really mind too much. My question is, what are some of the standard documents that should be written before starting development? I'm familiar with the following:

  1. Some sort of proposal (What the problem is, options to solve it)
  2. Requirements document (What the finished application will do)
  3. High Level Design (Big picture of how the application will work, including any screenshots or mockups)
  4. Low Level Design (method headers, more nitty gritty technical details)

What others am I missing? Did I mention anything that no one really ever does? I was asked recently for the "Developer's Documentation" which I was told was like a requirements document but for developers. I had no idea what they were talking about. I eventually gave them a list of taks with time estimates (making sure nothing was over 1 day) which they seemed to accept without any comment. I've also been asked to write some sort of testing plans in the past. What are some good resources (or examples) of these sorts of documentation?

EDIT: Use cases are another good documentation to have. (jaxvy)

+1  A: 

A good resource on what documents should be generated and when is the OPEN/Metis white paper available from www.openmetis.com.

Disclaimer: I am the author of this white paper. I am not trying to advertise my work, but to honestly reply to a question. Hope it helps.

CesarGon
I'm not talking about generated documentation for code, but documentation that is written by hand before any code is ever written.
Ryan Elkins
Of course. The resource I mentioned discusses exactly that: the requirements, specification and design documentation that one is supposed to create before any code is written.
CesarGon
+4  A: 

What others am I missing? Did I mention anything that no one really ever does?

4 is something that no one really does.

Method headers and classes that's something you come up with during coding phase but not when writing a proposal. I'd be surprised if you could do it before hand.


  1. Is very good

  2. Requirements may be changing continuously along with UI mockups that will need to reflect those

  3. Also very good

  4. Not needed and not really doable.

Developer Art
4 is indeed for the trenches.
pst
I meant those as 4 separate documents, not part of a proposal. It's more like once a decision is made ont he first one, you go to the second, once you have an approved version of that you go to #3, etc.
Ryan Elkins
Yes, and #4 will be embedded in a series of larger documents called the source code, in every place I've worked at. Also, #3 should change a whole lot less than #2, as Developer Art points out.
David Thornley
Agreed. #4 is sometimes demanded by micromangers, but it's a waste of time because it is subject to so much change during the coding that it is obsolete before you call it done.
Paul McMillan
+4  A: 

I think writing use-cases are very helpful to extract the necessary requirements of an application.

jaxvy
+1  A: 

High level Entity Relationship Diagrams and Flow Control diagrams can be useful as well as they map out in a graphical format what is supposed to happen. Not always created or used, but I try to create them as much as possible since it helps me when I start to code and helps the stakeholders know that I'm understanding what they want. The Flow Control diagrams are especially useful for me in this as I deal with complex mathematics and decisions.

Tom