Must-have development documents

11.09.2009 16:20Comments
Following with my previous post about the basic structure of source control, I said that it is very important to have a "Documents" folder. In that post, I also recommended to put the Architecture and Project Overview documents in this folder. I figured I'd further explain some of my favorite documents:
  • Project Overview
  • Architecture
  • Release notes
  • Roadmap
These are not the only ones I consider important, nevertheless,  I feel they really help to set the course for us developers to start doing our jobs! Project Overview This is the first document I like to read before digging into the code. At the earliest stages of the software development process, we usually get to know the domain of the application (analysis), and extract the domain's vocabulary. If we did this, then our code should be designed to reflect this domain and using it's vocabulary, thus making it very important for people joining the project to be aware of the domain. Apart from the domain itself, the project overview should describe the purpose and goal of building the system. Knowing this, contributors of the project can think and propose better ways to achieve this goal, or even new features which can enrich the project, both from a technical or commercial perspective. This document shouldn't be extense, and it might even be better to make it a slide presentation, because even though we want to know the domain, we developers are eager to dig into the code! Architecture Document The second document which can help speed up our understanding of a project, is the architecture document. I've seen many architecture documents, and none of them were similar. Most of the times, this document's goal is to show the customer how the system will be structured, in early stages of the development process; and depending on the client, and the project, there are a lots of different things we could include in this document. Regardless of the structure and content of this document, I think reading this document should be helpful for every developer in the team. As a developer I want to see the following things:
  • Programming Language (including version).
  • Database engine.
  • Frameworks and libraries with it's links to documentation.
  • Project sub-systems.
  • Project components.
  • Project layers and each layer's responsibility.
  • Deployment model.
A note on sub-systems and components, is that we should consider sub-systems as parts of the system that could stand alone, without the rest of the project. Components on the other hand, are parts of the system that have a clear goal, but which needs of other components in order to add value to the system. An example of a sub-system, could be a "messaging sub-system" inside a social networking portal. When a possible example of a component could be an "encryption component" inside a membership provider. Release notes One of the basic documents in configuration management. It's goal is to describe a certain version. I find this document extremely useful when it's properly used. It's the file I would send to the customer every time I deliver a piece of code. This are some of the things I would like to find in this document:
  • Version!! If we tagged the version in the source control, then I don't see a reason to include the changeset/revision.
  • Description of the release.
  • List of features added from the previous version.
  • Historical features.
  • List of known issues. (unresolved bugs).
  • Installation guide.
Roadmap This is actually one of my favourite documents. I find this document very important in helping us know where we are standing, and what the customers expectations of functionality in the short and long term are. Maybe this document is more of a "Project management" document than a development-related document, however, it is always good to keep customer's priorities in mind. Another thing that I get from this document is how well we know the customer needs. If we can't manage to get a decent Roadmap, then we are failing to understand the customer's need, and that's not cool. On the other hand, if we do manage to get a decent roadmap, but this roadmap changes too often, then the customer is failing at setting their own goals.

comments powered by Disqus