Documenting a new feature

Question

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?

Answer 1

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.

Answer 2

I don't know how to document this kind of stuff

Well, ask yourself what a potential reader would like to know. Fortunately, you don't have to guess, since you're this potential reader: “I want anyone should be able to understand the system [...] including me anytime in future.”

Depending on the actual feature you want to document and its complexity, the content of your document will vary. I suppose that you're writing it for developers only, which also limits its scope to technical aspects of the feature.

Usually, technical documentation includes:

• The overall architecture. It gives an overview of the feature, as well as its context in the larger system.

• The interfaces. That is, how do I use the feature, what it does, and what it doesn't.

• The dependencies. In other words, what this feature need to work properly, and how does it use those dependencies. This includes not only the code outside the feature, but also the things such as configuration, third-party APIs, files, etc.

• The specific design decisions which were taken, and the reasons of those decisions. This helps understanding why the feature was developed the way it was.

  This is particularly important for the aspects which were debated by the team. There are chances that newcomers (or the same team six months later) would start debating on the same subject, forgetting why was something decided in a way it was.

• The quirks. Similar to the previous point, this one puts an emphasis on a few very specific aspects of the feature which are too strange to be understood by just reading the code.

  For instance, it can be an explanation why instead of using a standard and straightforward approach, one have written three hundred lines of contrived code, and the explanation would be that there is some edge case where the straightforward approach wouldn't work.

Answer 3

Here's how:

1. Read.

2. Do things.

3. Briefly document the things you do.

4. Get someone else to work with those things.

5. Watch how well the documentation helps them.

6. Encourage them to improve the documentation by updating it with what it was lacking.

7. Delete needless things.

8. Condense what you can't delete.

9. Return to step 1.

I deeply believe that the last person to do a task is the best person to document that task. It's why I love wiki's so much. Anyone can edit them. Doing anything less than this will soon produce out of date documentation.