My favorite kind of work, when creating or implementing business systems, executes at a very fast pace. Unless the system is especially complicated, I don’t require UML diagrams or lots of other documentation. Business rules and wireframes often serve as acceptable requirements to get things going. Clearly, there is a lot more to any system, and appropriate documentation is essential. But, to get the code going, you don’t need a lot of documentation; at least, so it seems.
Keeping documentation light doesn’t mean there is no documentation. For example, I always create a database diagram for any database I have to build or integrate. It doesn’t take long if you are reverse engineering from an existing database. If you are building a database from scratch, it can take some time. Still, most tools generate SQL, and can get your project off the ground based on your diagram.
One thing I have found funny is that developers are asking for my database diagrams. Since the database mimics their object model to some degree, they often use it as a reference for their data classes. This is especially true if they are doing code-first implementation using Entity Framework. My diagram gives them everything they need.
Moreover, it helps them build REST calls from WebAPI. They can clearly see from the database diagram how the objects interact. They can tell what the different subject areas are to follow a common rest uri convention. The individual calls are easy to determine. They can decide what IDs to include in the uri, or if they should embed a complex object as JSON in the REST request body. I have even seen Angular developers using the diagrams, because they help to understand what the data looks like in their version of the Model.
Based on this I have found that, when I have to keep the amount of documentation to a minimum, a well laid out ERD can be used for a lot of things, if the Domain Model and the Database Design are close.
What documentation do you find to be the most useful when writing code? Share your experience in our comments.
Cheers,
Ben