• Business Objectives - high-level process needs that the software must address.
• Use Cases (User Stories) - specific logic or transactions, described using non-technical language. They should be detailed enough to provide developers with the kind of processing and validation logic they are to embed in the code.
• Test Cases - derived from use cases, they anticipate outcomes of each use case, given a set of specific starting data, and become tools to measures software effectiveness.
• Technical Architecture - describes technologies (development platform, hardware, etc.) required to develop and run the software, a technical approach for designing the class hierarchy, transactional service requirements, and database infrastructure.
• Project Plan - a pathway for the software development cycle (typically chronological) that outlines process, resource assignments, time allocations, project milestones, and deliverables.
• Code Comments - embedded directly into the code, they provide developers who look at the code insight into what occurs within each class, method, stored procedure, etc. In an ideal software development cycle the ratio of comments to code is roughly 50% (i.e., one line of comments for every 2 lines of code).
• Software Manual - familiarizes the end-user with the software.

Also remember that documentation evolves.  For instance, use cases created at the outset may change well into the cycle, as new information comes to light.  Allocate appropriate time to document changes and carefully consider changing business logic throughout the cycle, as these adjustments can have a profound impact on project delivery.

To simplify things further, there are several packages that facilitate software documentation:

• Ndoc - free Microsoft tool that reads the class hierarchy and code comments of software developed on .NET 1.0/1.1 frameworks and produces a structured HTML document.
• Castle - free Microsoft tool that reads the class hierarchy and code comments of software developed on .NET 2.0 frameworks and produces a structured HTML document.
• X.Doc - short for 'External Documentation', it is a Visual Studio add-in that manages and visualizes source-code comment documentation interactively in the IDE. Its main feature provides an easy way to 'externalize' the documentation comments using the documentation XML <include> tag.

Documentation is vital.  Once it becomes standard practice, projects become easier and outcomes improve.  If you would like to comment or receive more information, please contact us at info@somethingdigital.com.