Stack Overflow

Questions
Tags

Users

Badges

Unanswered

Ask Question

Take the 2-minute tour

Stack Overflow is a question and answer site for professional and enthusiast programmers. It's
100% free, no registration required.

Documents for a project? [closed]

I work for a CMMI level 5 certified company and one thing I hate about is the
amount of documents we prepare (As a programmer I already hate documents). We
have lots and lots of documents like PID(project initiation doc), Business
requirements, System requirements,tech spec, Code review checklist, issue logs,
Defect logs, Configuration management plan, Configuration management check
list(s), Release documents and lots...
Almost 90% of these docs are just done for the sake of QA audit :) .. What do you
think are the most important documents for a project? What documents can be used
up vote 11 in the long run by another developer?
down vote
Please share your good practices here. I would like to use them for my own projects
favorite
or the company I am planning to start in the long run.
10
Thanks
project-management project
edited Feb 17 '09 at 18:54 asked Feb 10 '09 at 16:42
share|improve this question
George Stocker Shoban
32.3k21107182 19k54191

closed as too broad by rene, TGMCians, Boann, ben75,

Zong Zheng Li Nov 18 '14 at 1:28
There are either too many possible answers, or good answers would be too long for this format.
Please add details to narrow the answer set or to isolate an issue that can be answered in a few

paragraphs.If this question can be reworded to fit the rules in the help center, please edit the
question.
See stackoverflow.com/questions/522684/ S.Lott Feb 11 '09 at 11:49
add a comment

7 Answers
active oldest votes
The key document is a good functional spec. There should be one and only one
reference document for a system.
Overdoing documentation proliferates a large number of small requirements and
spec documents every time someone changes a system or interface. For a system of
any complexity, before long you have your spec distributed around several hundred
assorted word, excel, visio and even powerpoint files. When this happens you lose
clarity about what is current or even whether you have located and identified all
pertinent documentation.
The BRD-SRD-Tech spec progression is based on an assumption that the business
signs off the BRD, a business analyst signs off the SRD against requirements
documented in the BRD and the technical specification is signed off against the
SRD. This generates a web of sign-offs, multiple documents with redundant
information and makes it difficult and clumsy to keep the spec documents up to date.
Because of this, subsequent requirements documentatation tends to take the form of
up vote 10 a series of change request and supplemental requirement and spec docs, each with
down vote their own sign-off and audit process. You gain CYA and audit trail (or at least the
accepted appearance of an audit trail), but you lose clarity. There is now no definitive
reference document for the system and it is difficult to establish what is current or
relevant to any particular activity. The net result is that your business analysis
process gets bogged down in forensic research, which adds overheads and latency to
delivery schedules.
A spec document should be built in such a way that there is one definitive reference
for any given system or subsystem. The document should be kept up to date and
versioned. Get a good technical documentation tool like Framemaker, so your
process can scale, and the document has some structural integrity of the sort lacking
on Word.
answered Feb 10 '09 at 16:47
share|improve this answer

edited Feb 13 '09 at 17:14

ConcernedOfTunbridgeWells
38.9k991161

add a comment
For me the only real document I ever use is a spec. The more detail the better.
However it doesnt need to be all completed at one time, and it doesnt need to be
particularly formal. What is far more useful to me than documents that are checked
and signed and double checked and double signed is always being able to get the
latest version of a document. And being able to talk to people about what they have
written, and get a decision in the case of any ambiguity. this is far more useful to me
than anything else.
up vote 4
To sum up: a spec is the only document I have ever found useful, however it pales in
down vote
comparison to having a project manager who knows the proposed system inside out,
and can make sensible decisions based on what they know.
answered Feb 10 '09 at 16:48
share|improve this answer

edited Feb 10 '09 at 16:59

Jack Ryan
5,37112162

add a comment
Documentation is like tofu -- most people hate it until they realize that under the right
conditions, it can be really good.
The problem is that what you consider documentation is mostly made for
documentation's sake. You, as a developer, don't see any immediate value in the
documents you produce because you know you can do your job without all the TPS
reports which you're required to make.
Unfortunately, I'm going to wager that there's not a lot you can do about in a company
where you're being forced to eat raw tofu all the time. You'll probably just have to suck
it up and write the docs which your company requires, but you can at least do one
up vote thing... you can write documents which at least are useful to you, and you can pass them
2 down along with your code for others who will maintain it.
vote
Aside from inline documentation, you could set up a wiki to be used by yourself and
people on your team. This type of documentation is searchable, which is already a big
plus to developers, plus it's more of a living document instead of a homework-like paper
you had to write. You already post to SO, so just think of your documentation as
pooling your knowledge in a more useful place.
answered Feb 10 '09 at 17:06
share|improve this answer
Nik Reiman
17.4k1665125
add a comment
up vote What do you think are the most important documents for a project?

Different people have different needs: for example the documents which the owner
needs (e.g. the business contract) aren't the same as the documents which QA needs.
What documents can be used in the long run by another developer?
IMO the most important document (except for the source code) is the functional
1 down specification: because what the software is supposed to do (as opposed to, what it is
vote
doing) is the one thing that can't necessarily be reverse-engineered. See also
http://stackoverflow.com/questions/400382/how-does-a-good-developer-keep-fromcreating-code-with-a-high-bus-hit-factor/400436#400436
answered Feb 10 '09 at 16:48
share|improve this answer
ChrisW
38.2k557133
add a comment
User Stories, burndown chart, code
answered Feb 10 '09 at 16:49
up vote
1 down
share|improve this answer
vote
Chris Ballance
18k1773121
add a comment
I'm a fan of the old 4+1 views:

up vote
1 down
vote

Use Case view (a/k/a user stories). There are several forms: proper use cases,
forward-looking use cases that aren't as well defined and epics which need to be
decomposed.
Logical view. The "static" view. UML Class diagrams and the like work well
here as a design document. This also includes request and response formats for
various protocols. Here is where we document the RESTful requests and
responses. This includes the REST URI design.
Process view. The "dynamic" view. UML activity diagrams, sequence diagrams
and statecharts and the like for here for design documents. In some cases,
simple narratives work well. In other cases, there's a State design pattern, and it
requires a combination of class diagrams and statecharts to show how the
stateful objects interact.
This also includes protocols (e.g. REST). Here is where we define any special
processing for the various REST requests.
This also includes an authentication or authorization rules, and any other cross-

cutting aspects like security, logging, etc.

Component view. The pieces we're building for deployment. This includes the
stuff we depend on, the structure of the modules and packages, etc. This is often
a simple component diagram or a list of components and their dependencies.
Deployment view. We try to generate this from the code as deployed. Since
we're using Python, we use epydoc to create the API documentation. We also
use Sphinx to import module documentation into this view of the software.
This also includes the parameters, settings, and configuration details.

This, however, isn't sufficient.

When projects start, you have to work up to this through a series of sprints.
1. The first sprints build just the use case view.
2. Subsequent sprints build an "architecture" to implement the use cases. The
architecture document has 4+1 views, but at a high level of abstraction. It
summarizes the structure of the model schemas, the requests and replies, the
RESTful processing, other processing, the expected componentry, etc. It never
has a Deployment view. We generally reference operator guide and API
documents as the deployment view of an architecture.
3. Then design-and-construction sprints build (and update) detailed 4+1 view
documents for various components.
4. Then release sprints build (and update) the deployment views.
answered Feb 11 '09 at 12:56
share|improve this answer
S.Lott
217k40305572
add a comment
up vote From the project point of view, the most important documents are those that normally
1 down include the word Plan, such as the Project Plan, Configuration Management Plan,
vote
Quality Plan, etc.
What you are describing is common in process improvements, and normally responds to
two major causes. One is that the system really is overeaching and getting in the way of
real work being done. Another is actually answered in your question: it is not that the
documents are only done for the sake of audits, and your focus should not just be how
usefull is the doc for other developers, but for the project or the company as a whole.
One usually looks at things from it's own perspective, sometimes it's necessary to look

at the general picture.

edited May 26 '11 at 14:07 answered Feb 10 '09 at 16:50
share|improve this answer
Kevin Worthington
4592517

krusty.ar
3,26111422

add a comment

Not the answer you're looking for? Browse other questions

tagged project-management project or ask your own
question.
asked 5 years ago
viewed 4670 times
active 3 years ago
Get the weekly newsletter!

Top questions and answers

Important announcements

Unanswered questions

see an example newsletter

Linked
70
How does a good developer keep from creating code with a low bus hit factor?
35
Application (Not a Markup Language) for Producing a User Manual
7
How much documentation is optimal for an Agile project?
11
Specific examples of Agile documentation?
5
Web Application Technical Document

Related
2
How much time should a Project Manager spend on a typical IT based project
6
the best or speedest way to understand uncommented and complex project
1
Using Java & .NET in Projects Development
1
Managing loads of small projects
1
What's the best way to start a project in mercurial when you already have files in the project?
1
What project management documents should i need to prepare for new web applicaiton
2
Project Sharing in Eclipse
2
project organization with R
1
Start a Python Project with Spyder?
3
What is index.js typically used for in node.js projects
Hot Network Questions

Why do LEDs have a maximum current?

How do I make interrogations interesting?

Buddhism vs. Nature and Real World

New Finder window opens maximized every time

Are there more outstanding warrants in Ferguson than residents?

Is this comma use unnecessary or wrong?

From what point could you view the most US states?

With the Deflect Missiles monk feature, does the player know the damage of the attack
before choosing to deflect?

Why did people start using CO2 (instead of e.g. oxygen) for carbonated drinks?

A researcher that I know organizes a symposium within a strange conference and has
asked me to go. What is the appropriate etiquette for declining?

What is the significance of the Hansen-Jagannathan bound?

Why specifically did Darth Vader choose Han Solo to test the carbonite freezing?

Can I safely run 595 watts of lights with a 600 watt dimmer switch?

Is there an effective method to retrain your muscle memory?

Is my sample homogeneous?

Most efficient way to square each element in a sorted array, keeping it sorted?

Web service to detect whether a picture has been published on the Internet before or not,
very fast

Having rigid bodies sliding off an animated object

Rotate a specific page of a pdf file?

Is there a more effective way to convince users to sign up with their social media
accounts?

How to thank a teacher in a thesis?

Sorting function that also works with containers having only forward iterators

Is `int main;` a valid C/C++ program?

Can our Sun become a black hole

tour help blog chat data legal privacy policy work here advertising info mobile contact us
feedback
Culture /
Technology
Life / Arts
Science
Other
Recreation
1. Stack
1. Progr
1. Databa
1. Photo
1. Engl
1. Mathe
1. Sta
Overf
amme
se
graph
ish
matics
ck
low
rs
Admin
y
Lang
Ap
2. Cross
istrator
uage
ps
2. Serve
2. Unix
2.
Scien
Validat
s
&
r
&
ce
ed
2. Met
Usag
Fault
Linux
2. Drupal
Fictio
(stats)
a
e
Answe
n&
Sta
3. Super
3. Ask
3. Theore
rs
Fanta
2. Skep
ck
User
Differ
tical
sy
tics
Exc
ent
3. ShareP
Comp
han
4. Web

(Appl
e)

Appli
cation
s
5. Ask
Ubunt
u
6. Web
maste
rs
7. Game
Devel
opme
nt
8. TeX LaTe
X

3. Graph
ic
Desig
n

4. Word
Press
Devel
opme
nt
5. Geogr
aphic
Infor
matio
n
Syste
ms
6. Electr
ical
Engin
eering
7. Andr
oid
Enthu
siasts

oint
4. User
Experi
ence
5. Mathe
matica
6. Salesf
orce
7. more
(14)

4. Seaso
ned
Advic
e
(cook
ing)
5. Home
Impro
veme
nt
6. Perso
nal
Finan
ce &
Mone
y
7. Acad
emia

3. Mi
Yode
ya
(Jud
aism
)
4. Trav
el
5. Chri
stian
ity
6. Arqa
de
(gam
ing)
7. Bicy
cles
8. Role
playi
ng
Gam
es

uter
Scienc
e
4. Physic
s
5. MathO
verflo
w
6. more
(7)

ge
3. Are
a
51
4. Sta
ck
Ov
erfl
ow
Car
eers

8. Infor
matio
8. more
n
9. more
(10)
Secur
(21)
ity
site design / logo 2015 stack exchange inc; user contributions licensed under cc by-sa 3.0 with
attribution required
rev 2015.1.5.2144