Knowledge management and tools in this field are becoming more and more critical
for companies, according to a Gartner® 2022 study
. Since the COVID crisis, employees have worked remotely from anywhere, leading to a momentum of asynchronous
communications. People also leave companies at a record level, so expertise and knowledge can quickly get lost. These are, among other reasons, the top 2 factors that put the light on the need for an efficient knowledge management system. For engineering teams and software developers, what’s the impact?
Understand the diversity of knowledge for software developers
Software Engineers may require various information when doing their job:
- Technical procedures: how to set up/build a project, install a library in your laptop, deploy software, … most of this material will look like tutorials or how-to guides. If you read them, you probably try to accomplish concrete.
- Informative content: a big picture of the architecture of a project, the declarative list of the servers used for our development environment, the CI/CD processes, the links or communications between our services… If you read them, you probably look for answers or discover a new domain and try to get familiar with it.
- Required knowledge to get jobs done: this can be heterogeneous, but developers will only be able to finish their work with them. I’m referring to API documentation, User stories, acceptance tests, or Designs/Mockups, for instance.
- Engineering guidelines: this ensures developers design solutions according to the organization’s principles and standards. This refers to coding standards or best practices for a language, framework, or architectural patterns. These guidelines ensure consistency within and across teams of developers.
Knowledge management and tools: which ones to use?
If we look deeper into this diversity of knowledge, we can observe they provide different answers to the following questions:
- How often should this knowledge be hit? (read by developers)
- How often is this knowledge updated?
- How many people should be involved in maintaining this knowledge?
- How necessary is this knowledge when onboarding a new engineer?
Let’s take an example to clarify.
Consider a technical procedure
to build & deploy an app on your laptop. We can reasonably assume that it will be read only once for each new developer on the project. Someone will update the documentation if there’s an issue or if something is outdated. That’s a basic recipe!
As a second example, assume there are 100+ software engineering working on React code daily. The best coding practices
related to React that should be followed in your organization have different requirements:
- Defining one Guru that will write down all React best practices is tricky. Other engineers should be involved in the process.
- This knowledge should be easily available. When writing code or doing a review, it makes sense to have it close to you.
- This knowledge can be frequently updated. People should be informed if it happens.
- Each new onboarded developer should get familiar with it.
So for each piece of knowledge needed by developers, remember to consider these four questions above to figure out the best locations and tools to use.
Example of tools to deploy
Here are some examples of tools that developers are familiar with**:**
- Technical procedures: Wiki tools such as Confluence or Notion are good candidates for that. In a previous post, we’ve listed many knowledge base tools. Embed some “how-to” guides in the Git repositories make sense if this procedure is contextual to a project.
- Informative content: Wikis are also acceptable for this. We can also mention GitHub pages and other Wiki based on Markdown that can be tracked on Git.
- Engineering guidelines: Many teams also use Wikis for that purpose. Still, they have limitations: lack of integration with developers’ tools (IDE & code-review tools), and keeping this documentation up-to-date is challenging. Pushing the information to developers when they don’t follow a best practice is also out of the scope of these tools. Promyze stands as a new alternative and is dedicated to best coding practices sharing. This is the result of a best practice in Promyze:
- Required materials: Jira, Trello, or your favorite project management tool will record user stories and business requirements. Figma or Adobe UX will help front-end developers, and Swagger will help you to create nice documentation for your API.
There must be definitively other categories of knowledge required daily by software developers. As the intro says, IT companies should be generous regarding knowledge sharing
. It can be an excellent opportunity to think about which kind of knowledge you currently record, in which tools, and how often they’re hit and should be
Feel free to share with us your opinions on that topic 😉