I ended up talking about knowledge management quite a bit at Agile Games 2018 and Mob Programming 2018. I don’t have a lot of formal training in this area, but it’s something that I’ve focused on a lot, and I’ve learned a lot from people who have studied it a great deal. Rather than respond directly, I decided to add a blog post about it, to benefit more people. This is an unordered list of these tips. I would love to hear your additions or feedback on it.
Push vs Pull Communication Channels
There are two different general ways of communicating information: Push and Pull. Push is when you send information out to recipients and they get notified (email, Twitter, Slack, etc) and Pull is when the recipient seeks out that information that was published earlier (Website, wiki, CMS, documentation). Using the wrong type can prevent the recipients from having the most recent information in a timely manner. The main deciding factor is, is it more important that people know about this information as soon as possible (changes to policy, status/availability updates, issues), or that people have the information when they need it (requirements, specifications, resources, environment details). Many tools can do both, like wikis, which allow people to get notified of updates). Email doesn’t work nearly as well as you would think at either push or pull, because most people in technical fields get so many emails that they find it hard to both notice and respond to timely emails and categorize those emails so they can find them later.
Lower The Barrier To Information Sharing
Creating and updating documentation is rarely the most favorite part of anyone’s job. It’s rarely prioritized when the work is planned out, if it’s budgeted at all. Starting to write documentation seems to be much harder than adding to it, so making it easy to get started is a big deal. A little bit of good documentation can be a whole lot better than no documentation. There are several ways to make it easier:
- Create a culture that values knowledge management at all levels: If the culture from the top does not value knowledge management, and time spend “not coding” is seen as wasted or overhead, then knowledge management will never get the time, resources, and attention required to do it right. If team members know that time spent on sharing knowledge won’t be appreciated, they are less likely to focus on it. It’s also important to convince the technical community of the benefits to them personally, like not getting stuck being “the database guy” or “the owner of the Therblug component”.
- Create templates: You can either create generic templates for the kinds of documentation or information sharing you expect, or identify an existing one as an exemplar. “This is what a component documentation home page should look like”. “Here is an example release communication”. “Stories should have a format like this”.
- Use a tool that makes it easy to iterate and easy to find information: If your way of creating documentation is to write a word document or PDF and upload it to a shared drive, it’s not very likely you’ll see a 1.1 version, let alone a 2.0 version. In part that’s because a word document is not a very good collaboration tool, and shared drives don’t make it easy to find things. I am a huge fan of wikis.
- Wikis let you truly collaborate (some in real time)
- Wikis allow endless hyperlinking, instead of forcing one path to each document like a shared drive, and dynamic links in the text to other pages and people.
- Wikis make formatting very easy so the writer can focus more on the content
- Wikis usually have subscriptions to topics to notify interested parties of changes and additions
- Many wikis allow enough security that some sensitive information can be published to a limited audience
- Many wikis are versioned, allowing everyone to see changes over time, and revert undesirable changes
- Wikis often let you export pages as HTML, PDF, or DOC if you need to distribute the information externally
- Creating a new page in a wiki is usually as easy as referencing the name on an existing page
- Wikis have built in search engines
- Maintain distribution lists: Recording the information is only half the battle. It needs to be delivered to the right people. Relying on people to keep track of everyone in each group, and even which groups are interested in which topics, is error-prone, especially in a growing organization. Mailing lists can be helpful, but the best tool for maintain distribution lists is something that can be used by several channels, like Active Directory/LDAP.
- Divide up the work: Sometimes there’s only one subject matter expert in an area, but it’s often the case that different people know all, or different parts. Instead of putting the burden on just one person, you can have different people work on different parts, or have reviewers contribute to the initial effort.
Know Who Knows What
No matter how much effort you put into knowledge management and knowledge transfer, there’s bound to be areas that are best known by one or two people. It’s a good idea to keep track of who your subject matter experts are. Make sure they are valued for their knowledge, but not to the point of job security through secrets. Consider subject matter expertise when letting someone go from the group, and when looking to bring new group members up to speed.
Not all knowledge is best recorded sometimes a demonstration work better, and sometimes mastery only comes from real-world experience.
Drilling Down To The Details
Starting with the high level and drilling down to the more specific can make the information both easier to read and easier to write. Writing the high level first can function as an outline, guiding what to write later, and letting you know when you may be done. Reading the high level first gives the reader context.
- Different roles/groups need different levels of detail. Project Managers may need a list of components and their functions, but the business analysts will be much more focused on the details and rules of each.
- If you look around at open source software projects, you will find a lot of their websites are written blog style, so you know what’s happening, but not a single paragraph on the home page describing what that project is for and when you would use it. You’ll find the same in many companies.
- You can add tremendous value by having at least a single paragraph for every component at work giving it’s context, and a list of those components and TLAs (Three Letter Acronyms), with links to more information
- Drilling down to the information does more than separate the detailed from the specific; it can help the reader find the information when they don’t even know what it’s called
- Don’t forget to not only drill down, but crosslink related topics. These links can be important to people trying to understand the big picture
- If your tools permit it, keep the specific details in separate documents than the general documentation, referencing the former in the latter. This is where wikis and web pages shine. In part this will keep both less cluttered, but it will also aide in maintenance. The details pages are bound to change more often than the high level pages. Do make sure to keep both in sync though.
Keep Onboarding In Mind
As you develop your knowledge base, you may find that the most logical arrangement of the information from an entity relationship point of view or a workflow /data flow point of view might not be the best way to discover the information as someone new to the group. Consider keeping a separate “onboarding landing page” with links to all the information someone new to the team will need to learn first. That may vary by role/group so you may need several.
Since it’s often hard for long-time employees to put themselves in the shoes of a newcomer, it’s a good practice to get the newcomers involved in the maintenance of this list, adding what they found to be useful, removing content that’s no longer relevant.
Keep The Knowledge In The Most Appropriate Place
Beyond push and pull communication channels, you will find other options of where to store a particular piece of knowledge, because most companies use lots of different knowledge management tools. For instance, if you have information about a detail of a particular component, do you record it in Confluence, or do you record it in Jira? It can be a hard call, but sometimes the defining factor can be how long the information is likely to be useful, and to whom. In the above example, if the information is an implementation detail for software not yet written, it will probably be better off in the story. If the information has to do with how the component interacts with external systems, it will probably be better off in Confluence.
You don’t always have to choose, though. Many of the tools commonly used for knowledge management today support integration with other tools, or at least external links. You can reference a Jira story in a Confluence as a clickable link, and vice verse. If the details are needed for both, it may make sense to put it in the longer-lived page in Confluence and reference it as a requirement in the story via a link to the confluence page.
Mark The Status Of Your Knowledge Base, And Keep It Up To Date
- Identifying status: If something is a work in progress or being reviewed, mark it as a draft, so others will know it’s not done yet.
- Completeness: If there is known missing information, make note of it in a searchable way so those with knowledge and spare time can more easily add to it.
- : It can still be useful as background on how you got to your current state, and past decisions. Marking it deprecated is crucial, as is linking to the updated information, if that exists. If one component is replaced with another, for instance, mark the old one deprecated and link to the new one, if your tool permits that
Keep your knowledge base up to date
- ! Documentation that is no longer accurate can be more damaging than no documentation at all. If you do separate the knowledge base into high level and detailed as recommended above, Make sure both are updated and consistent with each other
- : Make sure your living documents are really living documents. Part of that is collecting and acting on feedback and comments. Not all the information will come from the subject matter expert you expect, nor will updates to it
Pictures, Charts, And Graphs Can Add A Lot
Including images in your knowledge base can make it much quicker to grasp the concepts and details, especially when models, data flows, or work flows are involved, and for those who think visually. In the past, these were very difficult to maintain, and the source would often get out of sync from the published image, which often was in another format. Today, we have excellent tools that allow inline image creation which treats everything as objects and vectors, making updating them so easy, they can even be used in the design stage to share concepts still being worked on
- Gliffy is a great tool for creating images, charts, workflows, flowcharts, and all sorts of other diagrams, with everything treated as modifiable objects. It integrates seamlessly into Jira, Confluence, Slack, Trello, and more. I used it extensively at past jobs.
- Balsamiq is a rapid wireframing tool that integrates with Jira, Confluence, and Google Drive.
- Graphviz creates many different kinds of graphs.
- Lucidchart is great for creating charts, and also integrates well with Atlassian and Google, as well as exporting to many formats
Your knowledge management tool may have similar functionality built in.
Choose Your Words Wisely
It has always been a good idea to consider the ramifications of the words you choose, and there are many factors to keep in mind when doing so.
- Many words have unintended, sometimes unofficial connotations and associations: Be wary of using such words. Keep in mind that not all readers are from your background and culture, and may not know if those connotations and associations are intended or not.
- Be consistent with nouns: When using one word for a thing in one part of the document and a synonym in another part of the document, they may have the same meaning, but it may not be obvious to the reader that you are in fact referring to the same thing. This is especially important when the term is an internal one, as in the name of a component, group, or project. If they change over time, make sure references to them are kept up to date.
- Be consistent with conjugation: A tricky part of knowledge management and documentation is writing about things that don’t exist yet. Do you write “Will be” or do you write “is”? My recommendation is to write in the past tense as if the thing already exists, because updating it once it does exist can be a lot of error-prone work.
- Strive for gender/age/culture neutrality: In the past, this wasn’t seen as that big a deal, but today a lot of focus is being put on all forms of gender/age/culture bias. Documenting knowledge in a neutral way can be daunting, but it’s no longer acceptable not to. Fortunately, as this issue has come to the forefront, some conventions have arisen to make it easier to “get it right”, like using “they” as gender-neutral singular. Here’s an example of a resource covering some of these.