Documents Please!

I had an interesting discussion with one of our architects today that I've had on several prior occasions with Business Analysts, Managers, Developers and Business Users. The conversation centered around how to properly document the business and technical requirements for a project and an application. Every organization I've worked for has had their own documentation requirements, all were very proud of what they had, and every employee preferred what they had used at their prior organization.

I derive my perspective on documenation from a few basic principles:

1) The business users are the customers - the reasons for developing the application. The more difficult the document is for them to understand, the less value the document adds to the end result.

2) You must be able to trace a business requirement from definition through design. If you are unable to trace each requirement through to design, or you cannot trace a design element back to a requirement, your documents add no value.

3) Each step in the documentation process should add incremental value. If you are simply restating the same information in a different format, the do not add value.

4) Speed to market is king. Do not create documentation for the sake of documentation and recognize that the level of documentation required varies by size and complexity of project.

5) Technical documentation is useful in building an application but add no value in supporting an application. Business documentation - process flows, requirements, etc - add value to both.

6) Format is less important than clarity. A proejct team should use whatever format that adds clarity for everyone while still adhering to the basic tenets of SDLC - define it, design it, build it, test it, deploy it.

The discussion today centered around items 1 and 5. For projects I've managed and successfully delivered, I've chosen to limit the product documentation to:

• Business Requirements
• Process Flows (typically Swim Lanes)
• Screen Shots

If the project is large and/or complex, I add:

• Database Diagram (ERD)
• Class Definitions

While I see the value in Use Cases, UML and Sequence Diagrams when building applications where errors mean death (ie - NASA, Aeronautics) or major financial risk, I've found that documenting to that level of detail for a custom, corporate application adds unnecessary overhead to a project and adds little to no value going forward.

As far as technical documents post production, I pose this question:

If you are troubleshooting a problem, and you can only choose one, would you prefer access to the source code in debug mode, or access to the application documentation?

The only person I've ever posed this question to who has chosen the latter is the person I spoke with today. That doesn't make him wrong, just unique in my experience.

How do you document projects?