When it comes to software developers performing sufficient documentation of custom software development projects, much of the discussion usually centers around the pre-development design, code documentation, and installation/deployment processes.
The primarily objective for having this documentation is for other developers, or even the same developers, to revisit the code months or years later and quickly understand the intended function of the various parts of the code.
This documentation is mostly for the developers and support team, rather than the clients or end users, since the clients are usually more concerned with using the software as opposed to the code itself.
There is, however, one piece of technical documentation for which clients are often interested, but often gets overlooked – or receives little attention – during software development. That is database documentation.
Though creating reports is frequently mentioned in such requests, clients should know how their data is being stored, not only to maintain it, but to manipulate or migrate it in the future. From the client perspective, the data is more valuable than the software. Software is replaceable, business data is not.
Don’t think you’ll need it? Chances are you will.
Since the topic of database documentation doesn’t usually come up during the design process, it’s easy for developers to assume the client either doesn’t need or want it. That all changes, however, when the client requests it when the project is near completion. This adds a new task at a time of development when developers are under pressure to meet multiple approaching deadlines.
When developing custom software that uses more than a few databases tables, doing basic documentation of the purpose of each table and data column when they are created will put you in a far better position than delaying it to the end of the project.
Even though creating documentation earlier takes the same amount of time as doing it later, this time spent will be better measured into the overall progress of the project. This allows project managers to adjust resources accordingly, if needed, earlier on. In addition, the quality of documentation done earlier will be far better than something thrown together at the last minute.
Even if the client doesn’t ask for it, you should provide it anyway. This sends a good message to the client – you’re giving them something of value while looking out for their interests.
What appears obvious to the developer isn’t always so for the client.
From the standpoint of a software developer, it is easy to reach a conclusion that the database is “self-documenting,” in that columns such as “LastName” or “Phone” are sufficiently obvious. However, for columns of data that indicate data states to the software, or which vary based on business rules, what may appear obvious to the software developer won’t be for others.
For example, a column for sales orders called “OrderStatus” may have several possible values to indicate “New,” “Pending,” or “Cancelled,” while some may be only visible to the code.
In such cases, the people making database reports, or working on migrating the data to a new system years down the road, will need to know the possible values such columns can hold and what they mean.
In general, when it comes to documentation, it’s best to assume the person reading it has never seen code, isn’t a software developer, or has even used the application.
In part 2, we’ll cover how inexpensive database design tools can help make both the database design and documentation process easier.
