Gerenciamento de conhecimento: quais documentos são necessários e o que corrigir neles

O processo de documentação brota evolutivamente a partir de comentários médios no código à medida que a empresa cresce. Em algum lugar no meio do caminho, geralmente aparecem pessoas que dizem saber fazer o que é certo e que “este livro diz como fazer documentação” e traz algum tipo de processo difícil para a empresa. Além disso, há discussões, disputas, links para diferentes fontes com abordagens conflitantes e assim por diante. De fato, tudo isso não é acidental. Toda vez que encontramos esses momentos, significa que existem diferenças culturais. As tendências estão mudando e cada época oferece seus próprios livros.

Neste artigo, juntamente com Maxim Tsepkov, entenderemos quais lições podem ser aprendidas de diferentes abordagens, como criar documentos de projetos, o que colocar em um wiki, para que o Google Docs é adequado e o que sempre deve estar diante de seus olhos. De qualquer forma, por que precisamos de toda essa documentação. Ao mesmo tempo, abordaremos o tópico de gestão do conhecimento.

Programas do Projeto Cultura

A história do setor de TI é dividida em etapas, cada uma com sua própria abordagem ao gerenciamento de projetos: suas próprias idéias sobre sucesso, critérios de qualidade, organização do trabalho. Anthony Lauder em 2008 escreveu o livro "Cultura de projetos de software" (links para o original , tradução e resenha de Stas Fomin ), no qual identificou quatro períodos:

• científico;
• fábrica;
• design;
• cultura de serviço.

Cada um deles influenciou abordagens para o gerenciamento de projetos de software. E ninguém pensou em consistência um com o outro.



Sobre o palestrante: Maxim Tsepkov arquiteto e analista de negócios, navegador e especialista no mundo de Agile, organizações turquesas e dinâmica de espiral.

Eu uso uma periodização ligeiramente diferente, estendida até o momento. No esquema que proponho, a principal coisa que mudou é o escopo do projeto. Na era de P&D, era importante que o sistema de TI funcionasse, na era do RUP - que fosse feito pontualmente, na era do Agile - que fizesse o que o cliente precisa, e não apenas funcionasse, porque se constatou que eles frequentemente faziam a coisa errada.

Nos tempos modernos, um projeto de TI deve fornecer uma solução para problemas de negócios e trazer satisfação às partes interessadas. Não importa qual dos esquemas de divisão cultural esteja realmente correto, qualquer um pode ser usado, porque as diferenças estão apenas nos detalhes.


Mas é importante entender que a maioria dos livros didáticos sobre documentação foi escrita na era do RUP, na qual a organização do processo teve como objetivo atender ao orçamento e aos prazos. Isso não funcionou, mas os livros permaneceram e eles não escreveram novos livros .

O Agile, no início de seu desenvolvimento, girou o pêndulo na direção oposta, anunciando que o software de trabalho é muito mais importante que os documentos. E então havia formatos particulares: história do usuário, casos de uso, práticas particulares, mapeamento de história etc., refletidos nos documentos. Mas eles não escreveram livros didáticos abrangentes sobre esse assunto, porque entenderam que os livros didáticos não funcionam.

Agora percebemos que os projetos são diferentes e definitivamente não existem receitas universais - precisamos fazer o que é apropriado. Mas você não precisa inventar do zero, precisa usar modelos e amostras da mesma maneira que acontece, por exemplo, no design de interface. As interfaces são diferentes, especialmente em dispositivos móveis com uma tela pequena, você precisa colocar o que agora é importante para a tarefa, não existem coisas universais. Mas há um guia de estilo que fornece aprendizado, padrões e práticas intuitivos.

Ao desenvolver um guia de estilo, eles se concentram no UX. A documentação é a mesma - no guia de estilo Doc do projeto.

Espero que o relatório forneça princípios e conceitos, com base nos quais você possa melhorar a situação e resolver problemas com os documentos em seu projeto.

Documentos - para comunicação

A idéia principal, da qual procedo, é que os documentos não têm valor próprio, mas fornecem comunicação. Assim como as próprias interfaces não importam, elas fornecem ao usuário a funcionalidade oculta no lado do servidor.

A forma dos documentos, assim como as interfaces, é desenvolvida a partir dos objetivos da comunicação.

É importante aqui que, no caso de documentos de longo prazo, a comunicação seja distribuída ao longo do tempo. Hoje, você escreverá uma carta para si mesmo no futuro, quando será necessário refazer as alterações no recurso que você está fazendo agora. Voltando a ela depois de um ano e meio, lembre-se, descubra. Ou pode ser um desenvolvedor ou usuário completamente diferente que esteja operando seu sistema.

E se o documento for necessário para a comunicação, ele deverá ser direcionado . Com isso, nos comunicamos com pessoas específicas, e não enviamos para o mundo inteiro. Portanto, dividimos os documentos por objetivo e destinatário:

• para tomada de decisão;
• comunicação atual;
• preservação do conhecimento no tempo ("para mim em seis meses");
• transferência de conhecimento para outras pessoas;
• ajuda no trabalho atual, etc.

Cada destino possui seu próprio tipo de descrição, - ponto de vista -, seu próprio método de descrição .

Critério de qualidade do documento

O critério de qualidade será como o documento suporta a comunicação para a qual foi criado. A clareza do documento para todas as partes na comunicação é importante , o que limita a complexidade das notações. Quando apresentamos diagramas de classe, processos de negócios, status do documento para o cliente, não devemos esquecer quem lerá os documentos.

Os diagramas de classes na UML são uma construção de notação muito complicada, que, de forma simples, quando apenas classes e relacionamentos são desenhados, é quase intuitiva. Porém, quando o gráfico é carregado com todos os tipos de ícones adicionais, rapidamente se torna compreensível apenas para o autor e os desenvolvedores. Eles acham que transmitiram os significados. E o cliente acha que os desenvolvedores aqui fizeram algumas anotações para si mesmos, o que não faz sentido, mas eles não podem apagá-los. Ao mesmo tempo, esquemas simplificados devem economizar pontos-chave . Vale a pena usar tudo o que foi acumulado: hipertexto, links, textos, gráficos, áudio, vídeo para ser eficaz.

Esquemas e modelos são muito mais eficazes que o texto , porque a linguagem natural é ambígua. A experiência sugere que esquemas e visualizações são muito menos distorcidas e mal interpretadas que o texto. Mas os esquemas devem ser acompanhados de descrições que, importante, não duplicam o conteúdo, mas explicam a essência.

É necessário criar um dicionário de conceitos , uma única linguagem de projeto, mas é importante discutir não os termos, mas o conteúdo. Não há necessidade de discutir como usar a palavra para algum conceito. Precisamos discutir sobre quais conceitos e objetos temos nesta área e destacá-los. No tópico pluralismo terminológico e abordagens para trabalhar com ele, existem bons fragmentos no decorrer das palestras sobre o pensamento de engenharia de sistemas de A. Levenchuk.

O próximo ponto importante a ser lembrado ao projetar um sistema de documentação: "por que" e "por que" são mais importantes que "o que" . O caso de uso descreve o que precisa ser feito no sistema e, na história do usuário, há uma parte do "porquê": "Como uma <> eu quero < -> para < > ". Além disso, esse formato de história do usuário pode ser considerado como um modelo, ou seja, todas as peças devem estar. Eles não emergiram imediatamente da experiência, mas agora sabemos que o "porquê" é muito importante. O objetivo da história do usuário, o objetivo de qualquer requisito, é a comunicação distribuída no tempo do cliente (usuário) com o desenvolvedor e o analista como intermediário.

Nesta comunicação distribuída no tempo, é muito importante transmitir os significados para que o desenvolvedor tome decisões específicas. Sempre existem alternativas imprevistas: pela localização dos botões no formulário, pelo código, pela flexibilidade, pela generalidade da solução. Se a decisão for crítica, o desenvolvedor, é claro, interromperá e esclarecerá. Mas é melhor que ele naquele momento possa definir a tarefa de negócio e tomar uma decisão - a interrupção no processo de codificação é cara. A resposta para a pergunta "por que" na documentação ajuda muito, é por isso que apareceu.

A lição sobre "por que" e "por que" deve ser levada em consideração, mesmo se você usar outros formatos - para fixar os objetivos dos usuários e dos negócios, começando pelos objetivos do projeto. E, em seguida, o conteúdo das metas do projeto geralmente se resume a "negócios por algum motivo é necessário".

Não há necessidade de fazer cegamente coisas estranhas que a empresa não entende por que queria. Geralmente, ele tem fundamentos completamente racionais, depois de descobrir que coisas completamente diferentes precisam ser feitas.

Criamos documentos do projeto

Como projetar? Como qualquer outro sistema. A principal coisa mental que você precisa mudar é que não precisa pegar o modelo finalizado e copiá-lo, mas é necessário criar um novo, como fazer com as interfaces. É necessário assumir e projetar as interfaces do seu sistema, contando com toda a variedade.

A seguir, destacamos os casos de comunicação, determinamos os documentos que os apoiarão. Se a comunicação for distribuída ao longo do tempo, você precisará de uma pessoa responsável pela manutenção de documentos e pela aceitação competente de documentos. Porque, se depois de três anos descobrirmos que as descrições, digamos, não são muito inteligíveis, esse feedback será um pouco tardio, não haverá ninguém para transmiti-lo.

Mais adiante no processo de uso, avaliamos a qualidade e melhoramos da mesma forma que Usabilidade e UX.


Para projetar, você precisa de circuitos. Um esquema conveniente é o modelo V , que mostra a cadeia do projeto como um exemplo de abstração e entrega do resultado.


Se neste modelo colocarmos os artefatos clássicos de interação entre o cliente e a equipe, haverá: requisitos, tarefa de desenvolvimento, casos de teste, PMI , versões. Os artefatos terão algum tipo de backlog responsável.

Não é o fato de você precisar desses documentos. Isso se aplica especialmente aos requisitos e tarefas de desenvolvimento.

Há, por exemplo, uma alternativa - Design Orientado a Domínio, segundo o qual, em vez de requisitos e tarefas de desenvolvimento, um modelo de sistema é usado como um artefato coletivo. O modelo reflete o sistema e é conduzido por analistas, por um lado, e desenvolvedores, por outro.


Existem muitas opções e práticas. Todos eles estão intimamente relacionados ao processo de desenvolvimento, porque é no processo que as comunicações surgem. Observe seu processo e torne os artefatos adequados para ele.


O modelo V é um legado das eras de P&D e RUP. Desde então, as culturas mudaram e o design moderno é muito mais amplo. Em vez do conceito, surgiram coisas como necessidades do usuário e oportunidades de negócios. À direita, em vez de uma manutenção única, houve a entrega da próxima versão e suporte contínuo a tempo.

Exigências

Geralmente, existe um artefato chave entre o conceito e o início do projeto - o conceito ou Visão , que captura a posição inicial do projeto. Vamos nos correlacionar com o conceito à medida que o projeto se desenvolve, mas o mais importante é que é com base em que é tomada uma decisão desde o início, se o projeto deve ou não ser adotado.

Quanto o conceito ou visão deve ser elaborado em detalhes é determinado funcionalmente: o documento deve ser o mais curto possível, porque rapidamente, mas para que as partes interessadas tomem uma decisão sobre o início do projeto. Normalmente, o conceito deve refletir:

• idéia do projeto - uma oportunidade para os negócios: o que, para quem e como fazer;
• a viabilidade e viabilidade da ideia;
• interesses e expectativas dos principais stakeholders do resultado do projeto;
• design de produto e uso pretendido;
• avaliação dos recursos necessários para o projeto.

Além disso, interesses e expectativas podem mudar e, se isso acontecer, é importante consertá-lo a tempo.


No processo de trabalhar nos requisitos, é importante o limite externo do projeto . Com a mudança de culturas, as idéias sobre ele passaram de recursos como parte do design do sistema (na era de P&D) para recursos em função de um sistema que faz algo dentro de si e agora um recurso é um valor para os usuários. São diferentes níveis de artefatos; diferentes especializações são responsáveis ​​por eles: arquiteto, analista de sistemas, analista de negócios. Mas esta é uma abordagem funcional para o sistema.

Se falamos sobre satisfação do usuário, também apareceu uma linha de especializações: um designer de interface do usuário responsável pela satisfação do usuário com a aparência, Usabilidade - sobre uso e um especialista em UX que trabalha na masterização intuitiva da interface. Essa fronteira também está mudando. Em seu projeto específico, pode ser diferente, pois o desenvolvimento da empresa é uma coisa, para a qual existe um sistema de treinamento e o usuário não vai a lugar algum, como um contador da 1C, porque esse é o local de trabalho dele. E outra questão, por exemplo, desenvolvimento móvel. Se a rotatividade da equipe da loja for tal que o vendedor ou o lojista trabalhem em média por 3 a 6 meses, a questão de desenvolver um aplicativo móvel para o trabalho em 2 dias, e não em 2 semanas de treinamento, é relevante.


A manutenção dos requisitos deve ser consistente com a abordagem de teste e vice-versa. Se você possui os requisitos clássicos de Requisitos e Arquitetura, o Design Orientado a Testes é possível e o Design Orientado a Comportamentos é improvável. Como o BDD foi projetado para garantir que você formule um cenário para os usuários, ou seja, para um nível mais alto de abstração. Se não houver cenário nos requisitos, não haverá lugar para retirá-lo. Tais relacionamentos devem ser levados em consideração, e o custo de manutenção e verificação de casos de teste também deve ser controlado .

Artefatos de Foco Customizado

Uma classe separada de artefatos projetados para o foco individual diário. Estes são, por exemplo, os circuitos impressos e pendurados na frente da sala dos desenvolvedores . Uma das lições do Agile: um quadro de tarefas e um gráfico de gravação , pendurados fisicamente em uma sala ou configurados com teclas de atalho em formato eletrônico, são muito úteis. Um olhar distraído em pensamento apega-se acidentalmente e as informações são constantemente atualizadas. Da mesma forma, com esquemas arquitetônicos, princípios importantes.

É verdade que, se você pendurar tudo o que é recomendado nas paredes, elas ficarão tão suspensas que o significado de focar no documento diante de seus olhos se perderá, na massa eles serão percebidos como papel de parede. Nesse sentido, a pergunta "o que pendurar nas paredes, quais artefatos sempre estarão diante de seus olhos?" Também é um problema de design que precisa ser resolvido. Obviamente, exatamente o que é importante deve travar.

Diagramas de ER, um diagrama em camadas do aplicativo ou os principais componentes estão na documentação. Mas deitar na documentação ou pendurar na parede o tempo todo é uma grande diferença. Quando um desenvolvedor pensa: “Mas não cavar um buraco na API em cima do modelo em camadas de forma oblíqua?”, Porque na verdade ele reduzirá o tempo de desenvolvimento de um recurso específico (mas depois será acompanhado) e, enquanto isso, o esquema ficará diante de seus olhos, provavelmente ele verá que será um buraco. Se o diagrama estiver em algum lugar do documento, você poderá esquecê-lo temporariamente e escrever rapidamente o código que viola a arquitetura.

Conhecimento do movimento do projeto

No processo Scrum, existem pontos especiais para gerar conhecimento sobre o movimento do projeto:

• Demonstração - apresentação do estado do projeto para quem usa os resultados do seu trabalho e para outros interessados.
• Retro é uma auto-avaliação: se trabalhamos corretamente e o que pode ser melhorado.
• Reunião diária - sincronização das idéias da equipe sobre o movimento do projeto.
• Planejamento - sincronização de intenções.

É importante que essas reuniões de comunicação sejam espaçadas e focadas cada uma em seu próprio objetivo. Além disso, os formatos são desenvolvidos para eles. Existem livros inteiros sobre como conduzir retrospectivas e quais artefatos eles devem acompanhar. Além disso, alguns artefatos, como o código, são de ponta a ponta, porque as tarefas que precisam ser planejadas juntas são retroativas. Consequentemente, as retrospectivas da tarefa são adicionadas ao backlog, mas são marcadas, por exemplo, com cores. Trabalhamos com um ou outro - isso é normal.

Descrições de longo prazo

Ao criar descrições de longo prazo, a questão principal é determinar quais casos a descrição suportará . As opções podem ser completamente diferentes:

• Ensine um novo usuário a trabalhar com o sistema.
• Forneça informações de referência sobre as raras funções do sistema.
• Introduzir o design conceitual do sistema para um novo desenvolvedor.
• Para ajudar a recuperar o fragmento de dispositivo do sistema para o autor, para aprimoramentos.
• Descreva o sistema do módulo de dispositivo para desenvolvimento por um novo desenvolvedor.
• Forneça informações sobre o dispositivo do sistema ao engenheiro de suporte.

Nesse sentido, você primeiro formula a tarefa a ser suportada, depois cria documentos com o nível de detalhe necessário e assim por diante.

A descrição universal é detalhada, cara, irrelevante e também desnecessária, porque você não encontra as informações necessárias por causa de seus detalhes.

É necessário fixar o objetivo , avaliar a conformidade, lembrar: quanto mais detalhado o documento, mais caro.

Uma pergunta típica: as atas de pequenas reuniões regulares com o cliente devem ser claras e remanescentes do conteúdo da discussão apenas para aqueles que participaram da reunião, ou devem ser de tal ordem que possam ser enviadas a todos os que não participaram da reunião e também descobrirem isso? Esta é uma questão importante.

Obviamente, protocolos mais detalhados são muito mais caros . Isso deve ser gerenciado e as compensações podem ser aplicáveis. Por exemplo, insira um breve resumo no protocolo e consulte o vídeo ou áudio gravado para obter detalhes. Pode ser realmente útil, muitos retornam às gravações de vídeo.

Ao mesmo tempo, voltando ao "por que e para quê", não esquecemos de fixar a lógica das decisões no resumo, e não apenas "o que fazer". Resumidamente, mas é importante.


Com os documentos normativamente necessários de acordo com o GOST, você precisa entender se eles são necessários para a entrega do projeto ou para outra coisa. Como regra, documentos normativos garantem a comunicação do cliente com seus inspetores e devem ser escritos no volume em que é necessário, levando em consideração o uso do cliente. Às vezes, esses são documentos somente para gravação. Por exemplo, temos clientes para quem a documentação de trabalho e a documentação para inspetores são produzidas separadamente. Mas há quem queira que os documentos examinados funcionem, básicos. Dependendo disso, o processo de documentação é diferente, mas assim que entendemos sua finalidade, tudo está bem.

Comunicação transmite significados

Vamos discordar um pouco e discutir que a comunicação transmite significado.


Tudo começa com a suposição da era do RUP, que gerou a Abordagem Orientada a Objetos (OOP). Se decompormos o mundo em objetos e conexões , obtemos uma imagem inequívoca do mundo.


O cliente pode ver o mundo como uma coleção de agentes interagindo no modelo Haskell que trocam mensagens. Os agentes são os mesmos e as palavras são claras, mas a imagem é completamente diferente. O esquema, diferentemente do texto, reflete essa diferença. Portanto, usamos o esquema.

Uma maneira diferente de pensar é a norma . Modelos hierárquicos, as taxonomias passaram do desenvolvimento científico do mundo, no qual tudo é reduzido a uma forma estrita e "disposto nas prateleiras". Agora, com o desenvolvimento da Internet, o pensamento do mundo é popular como uma nuvem de tags com conexões, há até uma palavra especial - "folksonomy" . Esse pensamento é eficiente e operável. Marketing, a mídia é construída sobre isso. E o mundo dos engenheiros de TI, que estão mais próximos da imagem científica do mundo, está cada vez mais confrontado com isso.


Nesse sentido, você precisa conhecer e corrigir a diferença de pensamento . Caso contrário, você criará um sistema quadrado e o cliente preparará um furo redondo para ele. Então o processo de combinação começará e você terá que se contentar com algum crocodilo em forma de lágrima, porque um canto do seu padrão quadrado não pode ser cortado - é feito de metal arquitetônico sólido.

O que fazer é compreensível. Desenhe os diagramas . Devemos usar fontes prontas e conhecidas, por exemplo, UML. Mas lembre-se de que as anotações formais não são bem compreendidas por todos e muitos percebem esquemas informais e incompletos exclusivamente como figuras.

A fonte ortogonal de esquemas fora da TI é a metodologia SMD (consulte o relatório “Comunicação com uma estrutura de pensamento diferente - taxonomia versus folksonomia” ).

Princípios de gerenciamento de documentos

1. O documento não tem autor.

Ele vive mais que o primeiro autor, por isso trabalhamos coletivamente e não encaminhamos em cartas , usamos sistemas wiki. Você também pode usar o Google Docs, mas existem documentos separados, o que nem sempre é conveniente. Para produções de curta duração, o Google Docs é ótimo.

Uma conseqüência importante decorre do princípio de que um documento não possui autor e experiência em sistemas wiki: vi o que melhorar, faça imediatamente, a coordenação é necessária apenas por desacordo.

Parece que todo mundo entende que não há autor, mas poucos corrigem o documento de outra pessoa. A ortografia ainda é boa, mas se algo for mais complicado, o autor precisará escrever. Não, você precisa pegar e consertar . Todos os sistemas wiki têm notificações. Se o autor estiver interessado no documento, ele verá um aviso, veja o histórico de alterações e explique se você está errado. Mas, na maioria dos casos, ele não percebe ou decide o que é corrigido normalmente. O sucesso da Wikipedia é exatamente isso.

2. O documento é criado gradualmente.

Um documento grande se torna obsoleto antes de ser gravado. Basta conceder conceitos e detalhar conforme necessário. Fazemos a parte do documento relacionada à tarefa atual.

Os formatos que o Agile trouxe: história do usuário, caso de uso, mapeamento de histórias, diferentemente das produções monolíticas anteriores, não apareceram imediatamente. Eles estão focados precisamente na criação incremental de documentos, na elaboração incremental. Eles não estão em todo lugar, mas assim que decidimos enviar e detalhar os documentos de forma incremental, isso impõe as mesmas restrições à estrutura dos artefatos e ao código. Assim que escrevermos o sistema incrementalmente, e não o depurarmos completamente, devemos organizar o código de acordo: arquitetura de componentes, arquitetura de microsserviços - há muitas opções, mas não um monólito.

3. O conteúdo é mais importante que a forma.

Os requisitos formais de documentos não funcionam. Eles podem ser utilizados para economizar tempo no início, mas esse não é um critério de qualidade. Os critérios para a adequação dos documentos de uso das partes interessadas funcionam: listas de verificação e avaliação de especialistas.

Neste ponto, os regulamentos não funcionam - esta é uma lição no desenvolvimento do setor de TI, e não do setor de TI. Qualquer um pode editar nos sistemas Wiki, não há um longo processo de aprovação etc. O mesmo ocorre com as políticas de confirmação em muitos projetos OpenSource. Obviamente, há aprovações etc., mas é uma experiência materializada que deve ser usada.

4. Deixamos vestígios.

Este outro princípio importante diz respeito a atas de reuniões, resumos de conversas. Ou seja, conversamos ao vivo, conversando e anotamos um resumo de 1-2 frases no Rastreador de Tarefas. , , -, , .

. , , , . . , , . - , . , .

— , , .. , - , -, , , , . : , .

:

• Archimate.
• Archimate.
• - , Domain Driven Design.
• OMG Essence.
• viewpoint' ISO 42010.

. , , .

, , . , , , , , , , , : , .

, Wiki — , , , , , .. , - . CUSTIS MediaWiki. , Jira Confluence, OpenSource http://4intra.net. , , wiki- , .

— . Slack, Task Tracker Google Docs, .

. , wiki. wiki git, - wiki- , .

— , .

, , .

, « » . , : « , ?» , . , , « » , British Petroleum. , , , .


. . , .

, , 5–7 , . .

, , , C# , . .

— . — , wiki — , . . , , , . , , .

— , . BBC , , , . , , . , , .

IBM: — .

IBM : , - , . , . IBM , . , , , , , , , « , , ». . — , , .

• .
• .
• , .
• , .
• — .

mtsepkov.org (, , wiki) , agile , .

— . , : , , , , Knowledge Conf .

25 TeamLead Conf . , .