Where to start in agile-based documentations and what are the best practices to start with?

Question

We're currently working on our documentation and we sort of followed Scrum.

Which diagrams, charts, figures, and etc should I include in our documentation? Also, what are the best practices in documenting the "just right" amount of documentation?

Answer 1

There is an anti-pattern in many agile shops where they devalue useful documentation, likely due to a belief that "just read the code" is a reasonable answer.

The cognitive load for reading a few lines of code is significantly greater than the cognitive load for reading a few paragraphs of words; and as the saying goes, a picture paints a thousand words. As a programmer, I'm sure you've ran into situations where you spent hours spelunking through a code base only to finally ask someone who is able to illustrate the problem you're trying to solve with a few boxes and arrows on a whiteboard.

That said, premature documentation, like premature abstraction can be an anti-pattern. Instead, here's the process I go through when leading product and engineering teams:

1. Documentation is the first step towards automation. If you can't write down the words or draw a picture of a thing, it's going to be very difficult to automate it.
2. Tests may be documentation but tests are not documentation by default. it { is_expected.to return 200 } tells you nothing about what the expected endpoint is, what it is supposed to accept, nor what it's supposed to return.
3. Documentation is best when it supplements the invisible. In JavaScript and Ruby, for instance, I use documentation as a replacement for Java/C#'s explicit input and output return types.
4. Optimize your documentation for onboarding new team members and users. You may not get a new team member every day, but the information that's most useful for people who are just opening the code base/feature/module/library for the first time is also the most useful documentation when you wind up coming back to it in a few months and can't quite remember what the motivation was for the library in the first place.
5. When it gets out of date, delete it! Just like you delete dead code. Better to stumble due to missing rather than misleading documentation!
6. In that vein, disposable diagrams are sometimes better than editable ones. Disposable diagrams are often lower fidelity and distilled to their essence while editable ones get out of date due to over-specificity. One of my colleagues draws diagrams on A3 paper and takes a picture of them. I prefer to use my iPad to sketch things using a drawing app. In each of these cases the goal is to get things out of our heads into the world that can be recreated without significant cost.

I hope this helps!

Answer 2

Code is your most useful documentation because it's the only document that's always up to date. Ensure your code is easy to read: well structured, well named and commented where necessary.

Beyond that, create what documents you feel are necessary. There's no hard rule like "class diagrams are a must have" or "sequence diagrams aren't worth your time". Just consider the following:

• The time you spend creating a document is not free
• Your product will continue to evolve, eventually invalidating that document (There's nothing inherently wrong with creating documentation with a limited shelf life. IF its immediate usefulness outweighs its total cost)
• The time necessary to update and manage your document is also not free
• The document is only useful if it is read.
  • Without need the above effort is wasted
  • If the same information could be gathered faster by reading the code the above effort is also wasted (Classic example: API-docs that simply restate the function name)
  • If your documentation cannot be found then your effort is also wasted (I've seen too much documentation languish somewhere deep in a confusing folder forest on a non-indexed network drive where noone who doesn't already know the contents will ever find it)

This is not to say, documentation is never useful. Create documentation for the things that were really hard to figure out or nail down. Go through your notepads. Chances are you already have numerous notes on these topics from when you were wrapping your head around them the first time.

The one exception in my mind are requirements: You should always have a detailed and clear document explaining your requirements. No matter how murky the waters are where you are now you should always know where you are (supposed to be) heading.

Answer 3

• Document your processes, include all the things that really matter to you.
• Keep it up to date - always.
• Then make sure people see it, and use it.