Keeping team’s knowledge base

During team’s growth, the practice of keeping the knowledge base sound, looks like mission impossible. There are simply too many concerns to write down and maintain: picking a proper (=”searchable”) title to the knowledge base item, keeping the history of changes in the design and why they were made, adding some drawing etc. Text notes (and pretty pictures), what can we do, are getting obsolete extremely fast.

“How can we keep the team’s knowledge base without running after our tail?”

My team came up with this suggestion:

“Let’s keep the titles and put owners next to it, the rest can be solved with good communication and tests!”

Examples for such “knowledge base items” are, from our real list:

• Supporting Contextual Sign-In scenarios (Avish)
• Common CSS Classes for our beautiful look-and-feel (Moran)
• Creating and using pretty-URL routes (Ken)
• …

We broke it into domains like “basic architecture”, “common features”, “cross-cutting concerns”. Now the list is easy to search at (wiki) and fun to maintain.

This work extremely well if:

• Code-reviews are done on a regular basis. This means that at least 2 developers can talk about each knowledge base item.
• Tests are written to built great confidence (to refactor easily) in the code. I talk about unit-testing, integration testing, UI testing etc.
  • Great tests explain how to use the API and what should be expected from it.
  • Tests (mostly integration tests) explain the latest architecture.
• Comments in code should include the “why” behind the logic. Team members can add to it even more if needed, by talking with each other.
• New developers are exposed to the knowledge base, talking with the relevant owners. This is a great reference to look at.

Simple, short, effective!