|
How Much Documentation Is Enough?
Tips every developer needs for creating documentation that doesn't impede your software development cycle.
by Brian Noyes
Posted August 13, 2002
Documentation is a key artifact of the software development process. It comes in a range of formats, and provides persistent process information at major development stages. Software process documentation has its pros and cons, but it's never a good idea to have none.
Documentation captures important project information at major points in the development lifecycle. It helps developers convey progress and follow-through to customers or managers, and it's a handy reference for future projects that might require similar steps. It can help new personnel get up to speed on a project, its development timeline, and the best way to apply their skills. Depending on its details and metrics, it might be a reference for future proposals and bids.
Documentation does have pitfalls, however. It is often time consuming, costly, and does not directly contribute to an end product. It might be difficult, leading to decreased morale for a developer stuck with too many documentation tasks. It's also difficult to keep documentation synchronized with rapidly evolving software development production cycles.
To offset these drawbacks, companies need to answer some questions before beginning production: how much documentation, in what form, with what types of content, at what depth, for what audience? These are hard questions, and the answers will differ for every project. The amount of documentation needed will vary with different customer requirements, management goals, developers' skills and the software methodology. Successful answers must not overburden developers or the project budget, and must help prevent losing information.
Developers usually cringe at the mention of documentation. They don't like to do it. I think programmers innately believe that cutting code is fun, and writing documents is troublesome. I believe this will change, however, as the tools for documentation evolve, and the conceptual distance between documentation and code decreases through the use of modeling and automated documentation tools. Then documentation will become simpler and more enjoyableeven for a programmer.
Documentation usually follows the phases of the software development lifecycle: Requirements, Design, Implementation, Test, and Deployment. The amount of documentation dedicated to each phase depends on customer and management desires. A whiteboard discussion might be enough if you are employing an extremely agile methodology, but heavyweight processes that require peer review and management approval will require more.
Back to top
|
