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?

  • "but I have to prove myself in coming months and hence continue delivering" I hope that you don't deliver, just because you ahve to prove yourself ;-) – Christophe Oct 18 '17 at 20:02
  • @Christophe I am in probation period :) – CodeYogi Oct 18 '17 at 20:33
  • You could document your code using tests, for example using TDD – Constantin Galbenu Oct 19 '17 at 5:29
  • I suggest you change your goal from "high-quality documentation" to simply "useful documentation". If the documentation is useful then when compared to "no documentation" it will automatically give the impression of being high-quality. Since you seem to indicate that you don't have experience creating "high-quality documentation" then you have zero chance of accomplishing this feat. Simply reading about the topic will almost certainly lead you to create excessive documentation and not "high-quality documentation". Document what you needed to get the job done and this will go a long way. – Dunk Oct 19 '17 at 18:17
  • @Dunk you are making sense but the question is again what to document? and how? even for a getting the job done type. – CodeYogi Oct 19 '17 at 18:38

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.

  • You are right, I am looking for some pragmatic approach and your explanation makes sense. So, basically I can start the document outlining the Requirement in one para and then a real world example(maybe its technically a use case but in more informal way) and then coming to coding details. – CodeYogi Oct 18 '17 at 21:28

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.

  • I never said I don't want to learn or read books but in the current situation, obviously you can see that I am interested in these kind of stuff and self motivated too and hence I would love to expand my knowledge anyways. – CodeYogi Oct 18 '17 at 20:32
  • @CodeYogi: Fair enough. I removed the corresponding part of my answer. – Arseni Mourzenko Oct 18 '17 at 20:35
  • This is a pretty good outline, but perhaps you should also cover some of the things you should not document. For example, well-written method implementations (i.e. lines of code) should seldom require any documentation, other than perhaps the obligatory statement about the purpose of the method and the usual parameter descriptions. – Robert Harvey Oct 18 '17 at 21:02
  • @RobertHarvey but I haven't written any code yet, and one of the main purpose of my documentation is writing robust code. – CodeYogi Oct 18 '17 at 21:08
  • @ArseniMourzenko I don't see anywhere that you mention finding object or design database first vs define entity relationship? I hope you consider in account that the OP may be a beginner. – CodeYogi Oct 18 '17 at 21:11

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.