- ✓Technical documentation for a database typically includes a data dictionary, schema diagrams, SQL scripts, and a description of any stored procedures or triggers.
- ✓A data dictionary defines each table, column, data type, constraints, and the relationships between entities in a standardised format.
- ✓User documentation explains how to interact with the database application, written in accessible language for non-technical users.
- ✓Good documentation supports both the ongoing maintenance of the system and its eventual handover to a new team or developer.
- ✓Documentation should be produced throughout the development process, not left as an afterthought at the end of a project.
Listen to the full episode inside the course. Enrol to access all 80 episodes, plus assignments, tutor support and Student Finance funding.
Start learning →Alex: In our final Unit 4 lesson we're covering documentation. Sam, why does documentation matter so much for a database project?
Sam: Because a database that only the original developer understands is a liability. When that developer leaves, or when someone needs to extend or troubleshoot the system, the absence of documentation becomes a serious problem. Good documentation makes a database system transferable, maintainable, and usable by people who weren't involved in building it.
Alex: What are the different types of documentation for a database project?
Sam: There are two main categories. Technical documentation is aimed at developers, database administrators, and other technical staff. User documentation is aimed at the people who will actually use the system, whether directly through a database interface or through an application that sits on top of the database.
Alex: Let's start with technical documentation. What does that include?
Sam: The most important technical document is the data dictionary. This is a structured reference that describes every table and every column in the database: the table name, the purpose of the table, each column's name, data type, constraints, whether it can be null, and what it means. A good data dictionary tells you everything you need to know about the structure of the database without having to read the SQL scripts.
Alex: What else is part of technical documentation?
Sam: The entity-relationship diagram from the design phase is an essential technical document. So are the SQL DDL scripts used to create the database, annotated with comments where the logic needs explanation. If the database uses stored procedures, views, or triggers, those need to be documented too: what each one does, what parameters it accepts, and what it returns or modifies. Any known performance considerations, index choices, and configuration settings should also be recorded.
Alex: And user documentation?
Sam: User documentation explains how to interact with the system in plain, accessible language. If users access the database through an application, the user guide covers how to use that application: how to perform common tasks, what the different fields mean, how to search and filter records, and what to do if something goes wrong. It should be written with the assumption that the reader has no technical knowledge of the database itself.
Alex: What format should documentation take?
Sam: Format should be appropriate to the audience and the organisation. Technical documentation is often held in a wiki or a shared document system where it can be kept up to date as the database evolves. User guides are often PDFs or web-based help systems. The specific format matters less than the content being accurate, complete, and actually kept up to date when the system changes.
Alex: When should documentation be produced?
Sam: Continuously throughout the project, not left as a final task at the end. Writing documentation as you go keeps it accurate and ensures it doesn't become a bottleneck. The data dictionary should be started during design and refined during development. Test documentation is produced during testing. User documentation should be drafted before user acceptance testing so that users can provide feedback on whether it's clear.
Alex: Brilliant. So documentation is as much a part of the deliverable as the database itself.
Sam: Absolutely. A professional database product includes both. Thanks Alex. We move into Unit 5 and security next.