Feature Documentation – Documenting a New Feature Effectively

Architecturedocumentationdomain-driven-designenterprise-architectureproject-management

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:

  • a user story : this is a very simple and efficient way to document the user needs
  • a use case narrative : this pragmatic approach by Alistair Cockburn is ultra-simple to produce, is appropriate even for more complex needs, and is easy to understand by anybody involved.
  • a use case (2.0) : this is based on simple UML diagrams that focus on the user's goals and which are complemented by use-case narrative. The "2.0" was added by Ivar Jakobson to add slicing of use case, to facilitate an iterative approach.
  • if it's a business system, you can also consider a BPMN diagram. These diagrams present in an easy to understand fashion complex interactions between several actors.

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:

  • structure overview: a simple sketch of the main classes and their relation
  • interactions : A short narrative together could do
  • rationale: the reason why the design was chosen, as well as remaining design issues to solve.

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.

Related Topic