Documentation!

June 28, 2007 7:08 AM

What are the essential documents that all (software dev) projects should include?

There are certain "artifacts" that all dev projects should create above and beyond code and bugs, and most of that is documentation. What are the essential documents that all projects should include? UML diagrams, architecture, specs? Any links to reference would be appreciated.

posted by Null Pointer and the Exceptions to computers & internet (6 comments total)

Depends on whose point of view. If you're writing an enterprise application for a big business, you're going to need functional requirements, functional specs, code-level specs, implementation documents for future coders, and user manuals with graphics showing how to operate the software.

If you're writing a program for personal use, you may not even need any documentation except inline comments.

Hard to provide you with references and links without a scope!
posted by SpecialK at 7:49 AM on June 28, 2007

How CYA is your development culture? When I was at MegaCorp You've Heard Of Them Financial Services, Inc. the entire corporate culture was insanely so, and so the most essential written document of any project was a signed, baselined, detailed requirements document from the business/user community. Anything less than a signature on printed paper meant a vicious fight over scope creep, cost burdens, and playing "I know I asked for X but give me Z" games.

If the success of your project depends on dealing with flaky business units like that, such a document is essential.
posted by majick at 8:02 AM on June 28, 2007

I think that the right answer is a bit meta- you need to start with the docs that describe the process before you have the deliverables mapped out.

You really need a document that describes what is to be done, what the process will be for doing it, and how you will know that it is done.

In a professional services context, this first document is usually a combination of a proposal and a statement of work. In an internal software project, this can be a "Project Requirements Document", or Capital Expenditure Request.

Once these agreements are in place, you can drive down the rabbit hole into implementation; most folks seem to pursue a hybrid waterfall / agile approach these days:

- Some sort of requirements document describing the project in terms the business folks understand (use cases, functionality, etc)

- Some sort of strategic design document describing how the system is to be implemented (UML diagrams, database schema, etc). The more waterfall-esque you are, the more effort will be placed into adding tactical design into this set of docs.

- Some sort of test plan that describes how the system is to be tested and accepted by the client as complete. If appropriate, this is where you'll usually add in deployment information as well (server push, etc)

There are many other documents that get produced based on the methodology you're following.

If you are looking for templates and structures, the readyset folks ( http://readyset.tigris.org/ ) have a decent starting point- you'll need to pick and choose what works for your project, of course.
posted by jenkinsEar at 8:03 AM on June 28, 2007

All software? None. It's too vague of a question. Software's domain spans from hobby projects in your garage to guiding anti-missile missiles to running financial institution. What you must do depends on what your final client demands. If that client is you, you probably don't want much except that it works. If your client is the US government or the Bank of America, well, they are a little more demanding.
posted by chairface at 9:49 AM on June 28, 2007

Your contract.*

The rest will depend on corporate culture, your own "best practices", how many people you're working with, how many other programmers are helping, etc., but SpecialK gives a decent short-list. It's different every time.

* And I've worked without even that many times.
posted by LordSludge at 10:00 AM on June 28, 2007

I've got one that should damn well be in every software project: documentation of what resources your program requires and produces, along with notes indicating whether they are static or dynamic in size and their expected range and rate of growth.

Guess who just got a nice Surprise! on a production mailserver.
posted by Skorgu at 2:49 PM on June 28, 2007