Knowledge capture/documentation

Knowledge management in IT is often confused with the narrower topic of knowledge capture.

The practices of recording knowledge include:

*Recording of facts*For example:
- fixing the agreements at the time they occurred
- Information about new projects when work on these projects has begun
- Information about tasks when these tasks are first formulated
- Information about new infrastructure when it is created
*Writing documentation*For example:
- project-based
- architecture
- end-user

A huge obstacle to knowledge capture is the lack of skills in the articulation of the employees, and this challenge can be addressed in two ways:

Simplifying the process of entering knowledge
Training and development of the necessary skills of employees

Now, notice that fixing knowledge is not a panacea, and you need to be consistent in order for people to share knowledge. culture and to negotiate with people.

Knowledge-recording practices

With the fixation of knowledge, there are three fundamental problems:

No one writes documentation or records knowledge.
No one reads the recorded
No one is updating the recorded

The vast majority of companies don’t get any further than #2, which leads teams to the point of “We have a wiki, but it’s all terribly outdated and nobody uses it.”

So in order for knowledge capture to work, it’s critical that it be embedded in other processes. The process should not be able to continue if knowledge is not recorded.For example:

If you want to task-documentation Documentation should be part of the Definition of Done of your tasks, because the task cannot be considered complete until the documentation of the task is ready, and as a result, new tasks should not be taken into work until the old ones are completed.
In some cases, The process may not be started if the condition is not met. So, if you’re going to a conference and you don’t share a story about what happened at the conference, the next time you’re going to a conference, you don’t go to a conference.
Some of the knowledge can be recorded. at the interface of the units: introduce a rule to communicate only through the dock/fixed knowledge, or enter agreements on how to communicate in messengers and treat this communication as documentation.
Knowledge can be fixed Right in the place where the work is going on.Comments in code and git commits are also tools for capturing knowledge. For more, see Fact Recording.

Fact-recording, “digital footprints”

When we talk about recording facts, we mean that we record some information about what is happening at the moment when it happens, as it is now happening. And it usually does not involve much reflection, generalization, reflection and careful formulation of your thoughts. Fill out a form quickly and move on..

For registration of facts can include, for example: fixing tasks in Task trackers (Jira, Redmine, YouTrack, etc.), fixing accesses and passwords to services and servers, fixing agreements (aftermites, CRM systems, etc.).

Properly organized fact-recording dramatically reduces the cost of support, so it is important not just to record some information, but to indicate links to other knowledge base artifacts.

For example, when you make changes to your version control system (git, tfs, etc.), you can link those changes to a task that has a connection to the business reasons that prompted the task and the author, and when you open the code, you can see why each line is written and whether it can be changed later.

Writing documentation

By writing documentation, we mean that you write structured text, with neat, clear wording, perhaps with additional content in the form of diagrams / screenshots / examples of source code.

Writing these texts is a long, expensive process that requires skills, so it is doubly important to make content that is in demand and to develop the skills of employees to read content, and it is also important to build documentation into processes correctly: documentation written before implementation / in isolation from implementation is not very high value.

Documentation may be written:

It’s hard because they have other concerns, and often they don’t know how to do it, to help them build skills in writing and modifying content.
DocOps/Tech writers are easier to write, but they are not in the context of features, they need to pull information from engineers/developers through interviews, form and coordinate the structure and delve into the matchmaking.

Please note that the word "documentation" can be used to cover at least three things:

Reporting documentation – used for tenders and contracts and generally having little connection to reality and needs
Architectural documentation/analytical documentation is not understood by the layperson and is designed to help the system specialists (e.g. architects or analysts) remember everything.
User documentation is understandable to a third party and intended for onboarding into a product / project.

Challenges and measurement of effectiveness

The retention of knowledge helps:

onboarding of new developers
delve into unfamiliar parts of the project
sapporta, debug
design and decision-making
Onboarding of end-users of products

The solution to this problem is very difficult to measure, and it can only be measured qualitatively from the personal experience of many people. It is also difficult to calculate the financial returns of implementing knowledge-recording practices. These practices remain indispensable to protecting business critical knowledge..

Fundamental problems of all practices of knowledge fixation

When implementing knowledge-recording practices, knowledge managers consistently face three problems:

Almost no one makes notes.
Few people read the records they have made.
Records are outdated / erroneous – they know about it, but they do not correct it

Fixation

Investments in knowledge capture must pay off, balance between flexibility and documentation
People need to be trained at the right time to engage in fixation.
People need to be taught how to write properly (for example, many people are afraid to do documentation because they can’t write texts).

Reading

You need to teach people at the right time. read recorded
We need to make sure people know how to find the recorded information at the right time.

Correction

Correctibility of recorded information is an important criterion of all documentation practices.

It is very difficult for people to learn to correct other people’s texts, and, as a rule, few people grow up to the problem of correcting old documents.

Here are some problems:

Obsolescence of information
Duplication of information
I don’t know where and how to put your own changes.
It is not clear how to refactor the recorded documents.
There are no real responsible documents

Approaches and solutions

In the report How to implement a knowledge management system in business Vladimir Leshchenko talks about the implementation of the software product of the knowledge management system *enterprise*It’s all about selling, people’s motivations, the goals and objectives of the software product, and it’s all diluted with real-life stories from the practice.

In the report Trello – an effective knowledge management system for a small IT team (notebook) Roman Horin talks about the introduction of Trello as a *Knowledge management systems "on minimum"*It’s suitable for small companies, and it makes you wonder if you need complex, expensive systems.

Knowledge management: what documents are needed and what to fix in them Maxim Tsepkov reviews possible documents when working on a project, analyzes the feasibility of using each of them and dives into the historical reasons for the emergence of certain approaches to recording knowledge about projects.