An average IT company has requirements, a history of task trackers, sources (perhaps even with comments in the code), instructions for typical, important and complex cases in production, a description of business processes (from onboarding to “how to go on vacation”) , contacts, access keys, lists of people and projects, description of areas of responsibility - and a bunch of other knowledge that we probably forgot about and which can be stored in the most amazing places.
Knowledge =/= documentation. It cannot be explained, it must be remembered
How to make it so that those who need to learn something from this understand where and how to find it, and everyone who needs to be aware of certain things and agreements can instantly and accurately find out about changes in them.
In the final episode of the “Teamlead will call” podcast, the guys from Skyeng talked about knowledge management with Igor Tsupko is a member of the KnowledgeConf Program Committee and "Director of the Unknown" at Flant.
The full record is available as , and below we've put together some interesting tips and links to helpful material that was mentioned in the audio or expands on the information in it. It will be great if you also share your team's hacks and rakes in the comments.
First hack: you no longer need to know which system to look for
“I took our sources of knowledge and did a general search on them: such a single window with a filtering system to reduce the scope of the search. Yes, at the same time, you still need to monitor its quality, replenish knowledge bases, fight duplication and erroneous information.
One fastener to find that's it
But already now, about 60% of Flant engineers use this search at least 1-2 times a day - and usually find answers in the first or second position. And in the form of a proof of concept, there is an indexing of Google documents: all doxes, folders, van drives, and so on - all this is also easily driven into the internal search.”
The second hack: how not to miss the critically important in a bunch of chats
“If you work in a distributed team, then you probably spend a significant part of your day in Slack - and in which case you are used to doing something like this: “@myteam, help / look / enter the right one ...”. But there is a problem with the abundance of information - and a separate mention can be missed among other messages.
A bot helps us at Skyeng, through which you can write a message and tag any number of people or groups. We use it in cases where it is really important that people read or react: it will endlessly poke until you press the “I have read” button - it will not work to skip or ignore.
Backfilling question: what to do with the documentation?
“A lot of knowledge comes from techies, but not everyone knows how to describe it well.
After all, you don’t have any compiler or linter that would tell whether you are doing the right thing or not - and often we end up with incomprehensible, poorly formatted and incomplete text. Of course, you need to do it right, not because someone came and said “it’s necessary” - you yourself are doing well: in a month or two you will read and understand. Yes, and another person, opening the dock, will not immediately close it forever, realizing that it is no.
Part of the podcast dedicated to the question “How many people does it take to write good documentation or make a normal demo”
But the question remains: how much time to allocate for this and how to do it qualitatively?
And if there's an honest answer here: if business people aren't involved, and if they don't empirically feel the payoff from good documentation, there's a risk that the effort will have little payoff. It's more of a culture change story.
Otherwise, experience and mentoring will save you. Here, analogues of pair programming, progress tracking and code reviews can come in handy - showing best practices, poking at bugs and eventually nagging. ”
Bonus: “Come on, I’ll tell them so, they will understand”
The question “how much time to spend on it and at what level to do it” is important not only in the framework of documentation, but in general for the transfer of any knowledge. The demo is also a great example of information sharing. But there are nuances: for example, how to make them take minimal time.
Knowledge sharing channel among developers: internal reports, useful books, articles, etc. The structured squeeze is also stored in Notion.
In part, these problems are helped by the practice of internal reports. Once a week, 40-60 minutes are taken at not the most busy time - and the guys make a video report for colleagues from different projects. Key product frontend team - Vimbox - about your UI kit, which can be themed for any other project. The marketing development team - about the library for tracing and logging requests, which immediately interested several more projects. The Mathematics project team shared their experience of switching from REST API to GraphQL. The group lessons team is thinking of sharing how they first moved to PHP 7.4. And so on.
The list has been maintained since May 2018 and has over 120 entries.
All meetings are set up through a corporate Google Meet, recorded and placed in a folder on a shared Google drive during the day, and links to recordings are duplicated in the same Slack. That is, you don’t have to come if you’re in an emergency, and then watch at 1.5 speeds - usually the report itself takes up to 20 minutes, and the discussion - how it goes. But we do not go beyond the hour)
PS What worked and didn't work for you?
Useful links:
- Rodion Nagornov from Kaspersky Lab about and why it's not documentation (thanks for the link to Igor's channel , there are many more).
- Igor Tsupko from Flant about in your company
- Alexey Kataev from Skyeng (knowledge gaps in technologies and specific areas) in a distributed team.
- Sergey Goncharuk from Flant about reporting information - , if faced with a problem in a distributed team.
Source: habr.com