I have recently started working on a complex project and recently had a team meeting where a new feature was discussed. I am not happy with the current architecture, because the system is undocumented. However, I have to prove myself in coming months and, hence, continue delivering.
To prove my point that documenting helps, I need some proof of concept and I am thinking about implementing this feature with high-quality documentation which can capture user needs as well as design decisions taken from the developer's point of view. Basically, I want to make it such that anyone should be able to understand the system by having a look at that document including me anytime in future.
I am very new to this stuff, and I don't know how to document this kind of stuff, and I don't have time to go through different books.
Given the current situation, which document(s) can accomplish this purpose? And how do I do it?
Best Answer
To capture the user needs, you can consider one of the following:
To document design decision, you can of course use full fledged UML class diagrams, component diagrams, sequence diagrams, activity diagrams and state diagrams. But it's difficult to maintain all these diagrams onces the system is designed.
Alternatively, you could opt for a very pragmatic approach. Do not to document what can be easily retrieved from code (e.g. class structures with properties and methods), but focus on what's more difficult to grasp:
For a practical example, look at the GoF design pattern book (no need to read the book, but just the description of one of the patterns - there are also internet sites on design patterns). Becaus edesign pattern do exactly this: document a perticular design, when it is usable, and what kind of problems it solves.