Knowledge management: what documents are needed and what to fix in them

    The documentation process sprouts evolutionarily from mean comments in code as a company grows. Somewhere in the middle of the road, people usually appear who say that they know how to do it right, and that “this book says how to make documentation”, and they bring some difficult process to the company. Further there are discussions, disputes, links to different sources with conflicting approaches, and so on. In fact, all this is not accidental. Every time we come across such moments, it means that there are cultural differences. Trends are changing, and each era gives its own textbooks.

    Under the cut, together with Maxim Tsepkov we will understand what lessons can be learned from different approaches, how to design project documents, what to put in a wiki, what Google Docs is suitable for, and what must always be in front of your eyes. Anyway, why do we need all this documentation. At the same time, we will touch upon the topic of knowledge management.



    Culture Project Programs


    The history of the IT industry is divided into stages, epochs, each of which has its own approach to project management: its own ideas about success, quality criteria, organization of work. Anthony Lauder in 2008 wrote the book "Culture of software projects" (links to the original , translation and review of Stas Fomin ), in which he identified four periods:

    • scientific;
    • factory;
    • design;
    • service culture.

    Each of them influenced approaches to the management of software projects. And nobody thought about consistency with each other.



    About the speaker: Maxim Tsepkov IT architect and business analyst, navigator and expert in the world of Agile, turquoise organizations and Spiral dynamics.

    I use a slightly different periodization, extended to date. In the scheme that I propose, the main thing that has changed is the scope of the project. In the R&D era, it was important that the IT system worked, in the RUP era - that it was done on time, in the Agile era - that it does what the customer needs, and not just works, because it turned out that they often did the wrong thing.

    In modern times, an IT project should provide a solution to business problems and bring satisfaction to stakeholders. It doesn’t matter which of the cultural division schemes is actually correct, any one can be used, because the differences are only in the details.


    But it is important to understand that most of the documentation textbooks were written in the RUP era, in which the organization of the process was aimed at meeting budget and deadlines. This did not work, but the textbooks remained, and  they did not write new textbooks .

    Agile at the very beginning of its development swung the pendulum in the opposite direction, announcing that working software is much more important than documents. And then there were private formats: user story, use cases, private practices, story mapping, etc., which were reflected in the documents. But they did not write comprehensive textbooks on this subject, because they understood that the textbooks do not work.

    Now we realized that the projects are different and there are definitely no universal recipes - it is necessary to do what is appropriate. But you don’t need to invent from scratch, you need to use templates and samples in much the same way as it happens, for example, in interface design. The interfaces are different, especially on mobile devices with a small screen, you need to place what is now important for the task, no universal things exist. But  there is a style guide that provides intuitive learning, patterns and practices.

    When developing a style guide, they focus on UX. The documentation is the same - on the Doc style guide of the project.

    I hope that the report will give principles and concepts, based on which you can improve the situation and solve problems with documents in your project.

    Documents - for communication


    The main idea, from which I proceed, is that documents are not self-valuable, but provide communication. Just like the interfaces themselves do not matter, they provide the user with the functionality that is hidden in the server side.

    The form of documents, as well as interfaces, is developed from the goals of communication.

    It is important here that in the case of long-term documents, communication is distributed over time. Today you write a letter to yourself in the future, when it will be necessary to re-make changes to the feature that you are doing now. Returning to her after a year and a half, remember, figure it out. Either it can be a completely different developer or user operating your system.

    And if the document is needed for communication, then it  should be targeted . With it, we communicate with specific people, and not send to the whole world. Therefore, we divide the documents by purpose and addressee:

    • for decision making;
    • current communication;
    • preservation of knowledge in time ("to me in six months");
    • transfer of knowledge to other people;
    • help in current work, etc.

    Each destination has its own description type, - viewpoint - its own description method .

    Document Quality Criterion


    The quality criterion will be how the document supports the communication for which it was created. The clarity of the document to all parties to communication is important , which limits the complexity of notations. When we present class diagrams, business processes, document status for the customer, we must not forget who will read the documents.

    Class diagrams in UML is a very complicated notation construct, which in a simple form, when only classes and relationships are drawn, is almost intuitive. But then, when the chart is loaded with all sorts of additional icons, it quickly becomes understandable only to the author and developers. They think that they conveyed the meanings. And the customer thinks that the developers here made some notes for themselves, which make no sense, but they can’t erase them. Whereinsimplified schemes should save key points . It is worth using everything that has been accumulated: hypertext, links, texts, graphics, audio, video, to be effective.

    Schemes and models are much more effective than text , because natural language is ambiguous. Experience suggests that schemes and visualizations are much less distorted and misinterpreted than text. But the schemes must be accompanied by descriptions, which, importantly, do not duplicate the content, but explain the essence.

    Need to create a dictionary of concepts, a single project language, but it is important to discuss not the terms, but the content. No need to argue how to use the word for some concept. We need to argue about what concepts and objects we have in this subject area, and highlight them. On the topic of terminological pluralism and approaches to working with it, there are good fragments in the course of lectures on systems engineering thinking by A. Levenchuk.

    The next important point to remember when designing a documentation system: “why” and “why” are more important than “what” . Use case describes what needs to be done in the system, and in the user story there is a part “why”: “As <роль>I want <сделать что-то>, in order <достичь целей>”. Moreover, this user story formatcan be considered as a template, i.e. all parts must be. They did not immediately emerge from experience, but now we know that “why” is very important. The goal of the user story, the goal of any requirements is the time-distributed communication of the customer (user) with the developer and analyst as an intermediary.

    In this time-distributed communication, it is very important to convey the meanings so that the developer makes specific decisions. There are always unforeseen alternatives: by the location of buttons on the form, by code, by flexibility, by the generality of the solution. If the decision is critical, the developer, of course, will interrupt and clarify. But it is better that he at that moment could set the business task himself and make a decision - interruption in the coding process is expensive. The answer to the question “why” in the documentation helps a lot, that's why it appeared.

    The lesson about “why” and “why” should be taken into account, even if you use other formats - to fix the goals of users and business, starting from the goals of the project. And then the content of the goals of the project often comes down to "business for some reason is necessary."

    No need to blindly do strange things that the business does not understand why they wanted. Usually he has completely rational grounds, after digging out of which it turns out that completely different things need to be done.

    We design project documents


    How to design? Like any other system. The main mental thing that you need to change in yourself is that you don’t need to take the finished template and copy it, but you need to design a new one, how you do it with interfaces. It is necessary to take and design the interfaces of your system, relying on all the variety.

    Next, we highlight the cases of communications, determine the documents that will support them. If communication is distributed over time, then you need a person responsible for maintaining documents and competent acceptance of documents. Because, if after 3 years we find that the descriptions, let's say, are not very intelligible, then this feedback will be a little belated, there will be no one to transmit it.

    Further in the process of use, we evaluate the quality, and improve it in the same way as Usability and UX.


    To design, you need circuits. A convenient scheme is the V-model , which shows the project chain as an example of abstraction, and then delivery of the result.


    If in this model we place the classic artifacts of interaction between the customer and the team, then there will be: requirements, development task, test cases, PMI , versions. The artifacts will have some kind of responsible, backlog.

    Not the fact that you need these documents. This applies especially to the requirements and development tasks.

    There is, for example, an alternative - Domain-Driven Design, according to which, instead of requirements and development tasks, a system model is used as a collective artifact. The model reflects the system, and it is conducted by analysts on the one hand and developers on the other.


    There are many such options and practices. All of them are closely related to the development process, because it is in the process that communications arise. Look at your process and make artifacts adequate for it.


    The V-model is a legacy of the R&D and RUP eras. Since then, cultures have changed, and the modern design is much wider. Instead of the concept, things like user needs and business opportunities arose. On the right, instead of a one-time maintenance, there was a delivery of the next release and continuous support in time.

    Requirements


    There is usually a key artifact between the concept and the start of the project - the concept or Vision , which captures the starting position of the project. We will correlate with the concept as the project develops, but most importantly, it is on its basis that a decision is made at the very beginning whether to take on the project or not.

    How much the concept or vision should be worked out in detail is determined functionally: the document should be made as short as possible, because quickly, but so that the stakeholders make a decision about the start of the project. Typically, the concept should reflect:

    • project idea - an opportunity for business: what, for whom and how to do;
    • the feasibility and feasibility of the idea;
    • interests and expectations of the main stakeholders from the project result;
    • product design and intended use;
    • assessment of the resources needed for the project.

    Further, interests and expectations may change, and if this happens, it is important to fix it in time.


    In the process of working on requirements, such a thing as the external boundary of the project is important . With the change of cultures, ideas about it changed from features as part of the system design (in the R&D era) to features as a function of a system that does something inside itself, and now a feature is a value for users. These are different levels of artifacts; different specializations are responsible for them: architect, systems analyst, business analyst. But this is a functional approach to the system.

    If we talk about user satisfaction, then a line of specializations also appeared there: a UI designer who is responsible for user satisfaction with the appearance, Usability - about use and a UX specialist who works on intuitive interface masterability. This border is also shifting. In your specific project, it can be different, since enterprise development is one thing, for which there is a training system, and the user will not go anywhere like a 1C accountant, because this is his workplace. And quite another matter, for example, mobile development. If the store staff turnover is such that the seller or the storekeeper works on average for 3-6 months, then the question of developing a mobile application for work in 2 days, and not 2 weeks of training, is relevant.


    Maintaining requirements should be consistent with the testing approach and vice versa. If you have the classic requirements of Requirements and Architecture, then Test Driven Design is possible, and Behavior Driven Design is unlikely. Because BDD is designed to ensure that you formulate a scenario for users, that is, to a higher level of abstraction. If there is no scenario in the requirements, then there is no place to take it from. Such relationships must be taken into account, and the cost of maintaining and checking test cases should also be controlled .

    Custom Focus Artifacts


    A separate class of artifacts designed for everyday individual focus. These are, for example, those circuits that are printed and hang in front of the developers’s room . One of Agile's lessons: a task board and a Burn down chart , physically hanging in a room or configured with hot keys in electronic format, are very helpful. A distracted look in thought, accidentally clings, and the information is constantly refreshed. Similarly, with architectural schemes, important principles.

    True, it turns out that if you hang everything recommended on the walls, they will become so hung up that the meaning of focusing on the document before your eyes is lost, in the mass they are perceived as wallpaper. In this sense, the question “what to hang on the walls, what artifacts will always be in front of your eyes?” Is also a design issue that needs attention. Obviously, exactly what is important should hang.

    ER diagrams, a layered diagram of the application or the main components are in the documentation. But lying in the documentation or hanging on the wall all the time is a big difference. When a developer thinks: “But do not dig a hole in the API on top of the layered model obliquely?”, Because it will actually reduce the development time of a specific feature (but then comes around with accompaniment), and in the meantime the scheme hangs before your eyes, then most likely he will see that it will be a hole. If the diagram is somewhere in the document, then you can temporarily forget about it, and quickly write code that violates the architecture.

    Project Motion Knowledge


    In the Scrum-process there are special points for generating knowledge about the project movement:

    • Demo - presentation of the state of the project to those who use the results of your work, and others interested.
    • Retro is a self-assessment: whether we work correctly and what can be improved.
    • Daily meeting - synchronization of the team's ideas about the project movement.
    • Planning - synchronization of intentions.

    It is important that these communication meetings are spaced and focused each on its own goal. Moreover, formats are developed for them. There are whole books on how to conduct retrospectives, and what artifacts they should accompany. Moreover, some artifacts, like with the code, are end-to-end, because tasks that need to be planned together come from retro. Accordingly, retrospectives of the task add up to the backlog, but are marked, for example, with color. We work with one or the other - this is normal.

    Long term descriptions


    When creating long-term descriptions, the main question is to determine which cases the description will support . Options can be completely different:

    • Teach a new user to work with the system.
    • Provide reference information on the rare functions of the system.
    • Introduce the conceptual design of the system to a new developer.
    • To help recall the device fragment of the system to the author for improvements.
    • Describe the device module system for development by a new developer.
    • Provide information about the system device to the support engineer.

    In this sense, you first formulate what task you need to support, then you make documents with the necessary level of detail and so on.

    The universal description is detailed, expensive, irrelevant and also unnecessary, because you cannot find the necessary information in it because of its detail.

    It is necessary to fix the purpose , evaluate compliance, remember: the more detailed the document, the more expensive.

    A typical question: should the minutes of regular small meetings with the customer be clear and reminiscent of the content of the discussion only to those who participated in the meeting, or be such that they can be sent out to everyone who did not participate in the meeting, and they could also figure it out? This is an important issue.

    Obviously, more detailed protocols are much more expensive . This must be managed, and trade-offs may be applicable. For example, enter a short summary into the protocol, and refer to the recorded video or audio for details. It can really be useful, many return to video recordings.

    At the same time, returning to the "why and for what", we do not forget to fix the logic of decisions in the summary, and not just "what to do." Briefly, but it is important.


    With the normatively necessary documents in accordance with GOST, you need to understand if they are needed for the delivery of the project or for something else. As a rule, normative documents ensure the communication of the customer with his inspectors and should be written in the volume in which it is necessary, and taking into account the use by the customer. Sometimes these are write-only documents. For example, we have customers for whom working documentation and documentation for inspectors are separately produced. But there are those who want the documents to be examined to be working, basic. Depending on this, the documentation process is different, but as soon as we understand its purpose, everything is fine.

    Communication conveys meanings


    Let’s digress a bit and discuss that communication conveys meaning.


    It all starts with the assumption of the RUP era, which spawned the Object-Oriented Approach (OOP). If we decompose the world into  objects and connections , we get an unambiguously interpreted picture of the world.


    The customer can see the world as a collection of interacting agents in the Haskell model who exchange messages. The agents are the same and the words are clear, but the picture is completely different. The scheme, unlike the text, reflects this difference. Therefore, we use the scheme.

    A different way of thinking is the norm . Hierarchical models, taxonomies went from the scientific development of the world, in which everything is reduced to a strict form and "laid out on the shelves." Now, with the development of the Internet, popular thinking of the world asa cloud of tags with connections, there is even a special word - “folksonomy” . Such thinking is efficient and operable. Marketing, the media are built on this. And the world of IT engineers, who are closer to the scientific picture of the world, is increasingly faced with this.


    In this sense, you need to know and fix the difference in thinking . Otherwise, you will make a square system, and the customer will prepare a round hole for it. Then the process of combining will begin and you will have to be content with some teardrop-shaped crocodile, because one corner of your square pattern cannot be cut down - it is made of solid architectural metal.

    What to do is understandable. Draw schemes. We must take ready-made, well-known sources, for example, UML. But keep in mind that formal notations are not well understood by everyone, and many perceive sketchy, informal schemes exclusively as pictures.

    The orthogonal source of schemes outside of IT is the SMD methodology (see the report “Communication with a different structure of thinking - taxonomy versus folksonomy” ).

    Principles of document management


    1. The document has no author.

    He lives longer than the first author, so we work collectively, and  do not forward in letters , we use wiki systems. You can also Google Docs, but there are separate documents, which is not always convenient. For short-lived productions, Google Docs is great.

    An important consequence follows from the principle that a document does not have an author and experience in wiki-systems: I saw what to improve, do it right away, coordination is only necessary by disagreement.

    It seems that everyone understands that there is no author, but few correct someone else's document. Spelling is still fine, but if something is more complicated, then the author needs to go and write. No, you need to take it and fix it . All wiki systems have notifications. If the author is interested in the document, he will see a notice, look at the history of changes, explain if you are wrong. But in most cases, he either will not notice, or decide what is fixed normally. The success of Wikipedia is just that.

    2. The document is created gradually.

    A large document becomes obsolete before it is written. Suffice it to concise concepts, and detailing as necessary. We do the part of the document that relates to the current task.

    The formats that Agile brought: user story, use case, story mapping, unlike the previous monolithic productions, did not appear immediately. They are focused precisely on incremental creation of documents, incremental elaboration. They are not everywhere, but as soon as we decide that we submit and detail the documents incrementally, this imposes the same restrictions on the structure of artifacts as on the code. As soon as we write the system incrementally, and not completely debug it, we should organize the code accordingly: component architecture, microservice architecture - there are many options, but not a monolith.

    3. Content is more important than form.

    Formal document requirements do not work. They can be taken to save time at the start, but this is not a quality criterion. The criteria for the suitability of stakeholder use documents work: checklists and expert evaluation.

    At this point, the regulations do not work - this is a lesson in the development of the IT industry, and not the IT industry. Anyone can edit in Wiki systems, there is no long approval process, etc. The same with commit policies in many OpenSource projects. Of course, there is approve, etc., but it is a materialized experience that should be used.

    4. We leave traces.

    This other important principle concerns minutes of meetings, summaries of conversations. That is, we talked live, chatting and write down a summary of 1-2 sentences in Task Tracker. Usually we think that we will remember everything like that, but then force majeure happens, and after a week no one remembers what they agreed on then.

    Do not be afraid to write a resume yourself. The one who writes the resume fixes what they really agreed on . But do not bend too much. If communication continues, and new arrangements arise, then good. But in the case of a pause, the recorded may come in handy. Therefore, write and make the materials available to all participants.

    The purpose of the tracks is not to find the guilty, and restoration of circumstances, logic of actions, etc. For example, when you see some very interesting code that connects different fields or other check logic, it is very important to understand why it was written in due time, and whether the circumstances that caused it were still relevant. The traces will make it possible to understand: either the circumstances are in effect and this is a special case, or the circumstances are no longer valid and can be turned off.

    Typical Knowledge Models


    There are standard models:

    • Models for describing a business in Archimate.
    • Stakeholder Motivation Model at Archimate.
    • Object-oriented programming approaches ported to ontology development in Domain Driven Design.
    • OMG Essence project management map.
    • Scheme of multiple viewpoints of ISO 42010.

    Typical models should not be treated like dogma. They are too heavy if you follow the form, but are good for checking the content and structure.

    Only having determined the nature of working with documents does it make sense to choose tools, and not vice versa. As well as development frameworks, it makes sense to choose, realizing what kind of project there are, what kind of interfaces, interactions with the database, application server, and not postulate: this is a good framework, we will write on it.

    As I said, Wiki is a good option, because it is a common space for all documents, convenient teamwork, changes, searches, schemes, etc. I will not agitate for him, but I boast a little. We at CUSTIS have our own assembly of the MediaWiki engine. We did it a long time ago, even before Jira and Confluence, it is available in OpenSource and is available at http://4intra.net. I, for example, on it raised wiki systems for students when I taught.

    Short-term documents are a completely different matter. They are conveniently stored next to tasks in Slack, Task Tracker or in Google Docs, as links.

    Long-term is better to keep in the published documentation along with the code. There are their own tools, not a wiki. Although you can publish git in the wiki, which, according to the commit, will render something into wiki markup and publish it as a page along with manually written materials that are there.

    The main thing is not the documentation system, but the way it is used.

    We manage professional knowledge


    In addition to managing project documentation, there is professional knowledge management that does not apply to projects, but to technologies and processes.

    This is a separate industry called “knowledge management” . She was born when the West thought: “And how do we win in the competition after China blocks all patents?” They decided that they would compete with knowledge. There are many developments, for example, the classic book “Learn to Fly” on this topic, about the experience of British Petroleum. It is already relatively stale, but you can still learn a lot from it, just like from old OOP textbooks, we just take what we need.


    We listen to the pulse of time. Knowledge of technologies and methods of work is changing very quickly now. Practice ahead of theory, and it must be mastered by practice.

    К сожалению, по многим областям учебники никогда не будут написаны, потому что характерное время написание учебника 5–7 лет, а то и больше. За это время в современном мире он необратимо устареет.

    For example, the programming method in the mixed paradigm that appeared when the relational functional paradigm was dragged into C # was still not understood by OOP theorists. And programmers have been using it for about five years now.

    One of the effective ways to keep abreast of the pulse is through communication in the communities in the company and beyond. A meeting in the kitchen is good, and a general wiki is also good, but dead without communications. The exchange of professional knowledge should be organized in the company and beyond. You need to understand where in your company there is sufficient competence for the community to live inside, and where you need to go outside. Of course, the work of the community and the accumulation of knowledge has a price, so you need to manage the process and highlight key topics.

    Knowledge management lessons


    Knowledge can be - but how to find a person who possesses it. The BBC at one time found that when traveling for news, the knowledge about the local context that anyone who was already there was important. That is, regardless of whether it is an operator or a technician, knowledge of the context will be. In our terms, this means that the most important thing is not professional communities, but a common base of employees with travel information.

    A lesson from IBM: a professional does not understand the question of an amateur - we need translators.

    The idea of ​​IBM was this: to create a community in which people will write their questions on a particular topic, and experts will see and answer them. What is important, the experts were motivated for this. IBM is a large company and has launched many communities at once, but only a few have taken off. It seems like everywhere the conditions were the same, but it turned out that in successful communities, there were special people who monitored the entire flow of questions, and then routed them to the right experts, translating along the way and explaining to the expert that “this is a question for you, he asks about that , what do you know". That is, a professional often simply does not recognize the issue. Therefore, a separate useful competence in the issue of knowledge management is to understand the topic on the issue, and then transfer the question to the expert on the topic, so that he accepts it.

    To summarize


    • There is no ideal system for working with documents.
    • We are building a system for working with documents for a project.
    • Evaluate how the document system is adequate to the project.
    • In an existing project, it is better to go from pains and problems, improving.
    • In a new project - can be redesigned.

    The website of speaker Maxim Tsepkov mtsepkov.org (also, by the way, in the wiki format) has a lot of materials on analysis and architecture , project management and  agile , knowledge management .
    Documentation is just one of the issues of knowledge management. Many other important aspects, such as: engaging employees, creating a culture of continuous knowledge sharing, evaluating the effectiveness of knowledge management, processes and software, we will discuss at our professional conference on knowledge management Knowledge Conf .

    But first, on February 25, as part of a meeting at  TeamLead Conf , Maxim Tsepkov and Dmitry Simonov and I will try to solve one specific practical problem. Come, at the same time we will add to the list of pains for our conference.

    Also popular now: