Documentation

Writing code is not the hard part in programming, that’s actually the easiest one. Reasoning about domain, process and model is the hard part. Communicating the design to others is the hardest part. Documentation should be able to help with effective communication. Documentation should be implicit to the modelling language. Not an after thought.

Challenges

• Documentation represent the interactions and relationships between the objects of the system. However, it fail to convey the conceptual definitions of these objects.
• Behaviour of the objects and the constraints on them are difficult to illustrate using documents and diagrams. More often than not, the documents are just interaction diagrams representing the skeletons of the ideas.
• As the system evolves, documents lose their connection with the flow of the system becoming stale or irrelevant. On the other hand, comprehensive diagrams of the entire object model overwhelm the reader with details. Again failing to communicate effectively.
• A single visualization format doesn’t work for all types of communications or all types of projects.
• Developers should be able to visualize the system using different visualization formats. e.g. Component diagrams, Entity Relationship diagrams, Sequence diagrams etc.