In my opinion the two biggest drawbacks of technical documentation for developers are:
- It is rare to find technical documentation that not up to date. Teams rarely treat documentation as a living document, and without a concerted effort by the team to keep it up to date goes out of date.
- The documentation is not in front of developers when they need it most. For instance a new starter might read the database standards documentation in their first week, and not when they create something in the database.
Rather than have a lengthy word document, our team has opted for an example SQL script file that lives in the codebase. This overcomes the above obstacles:
- It is a living document - if something is lacking from it, a developer can edit it with suggestions. As it is part of the codebase the change is appropriately versioned in source control.
- The example SQL file literally lives in the codebase in the parent folder where we commit our SQL changes. This means a developer can easily refer to it or copy and paste from it when creating a new table, stored procedure, index, etc..
Here is our example SQL script file (with a few changes to make it more generic):