Geralmente, há um problema com a base de conhecimento corporativa dos desenvolvedores - ela se transforma em um vazio, porque não há motivação para preenchê-lo com uma pessoa responsável ou em uma varanda cheia de itens de um apartamento soviético, todos contribuem, mas eles escrevem aleatoriamente, as informações rapidamente ficam desatualizadas e nem sempre há tempo para atualizar.
Como evitar isso ou pelo menos reduzir os possíveis custos? Como aquecer sua base corporativa e luminária? Vou tentar responder.
Documentação de estilo de colaboração
Existe essa abordagem, documentação colaborativa, originalmente surgida no campo da medicina, quando a decisão de fazer um diagnóstico é tomada coletivamente pelo paciente e por vários médicos.
Um exemplo impressionante no campo da TI é o Google Docs, Wiki, Github, qualquer sistema que tenha convenções internas e a capacidade de trabalhar em conjunto em um projeto.
A idéia é incluir desenvolvedores, especialistas e críticos no trabalho de documentação o mais cedo possível, para identificar lacunas.
Por que isso é necessário?
Primeiro, reduzir o fator barramento é um gargalo no conhecimento corporativo, onde o número de detentores de conhecimento tende a se unir. Você precisa transferir esse conhecimento do chefe do desenvolvedor, de quadros brancos, ingressos, conversas na cozinha em um único espaço para que todos possam trabalhar com eles e contribuir.
Em segundo lugar, para simplificar a entrada de novos participantes em projetos, o que é especialmente importante para equipes distribuídas e equipes com um certo número de desenvolvedores de terceirização, bem como para as empresas que possuem uma área de negócios muito específica, a chance de encontrar um especialista pronto é zero.
Terceiro, para a formação de uma sólida cultura corporativa, transparência "não em palavras". Um desenvolvedor nesse ambiente entende claramente os pontos de crescimento profissional, que outras tecnologias ele pode experimentar na empresa e o que aprender.
O que fazer?
A documentação na base de conhecimento corporativa pode ser escrita por qualquer membro da equipe; essa oportunidade precisa ser simplificada para eles; eles sentirão que são os proprietários do resultado envolvido.
No entanto, você definitivamente precisa de uma pessoa que assuma as funções de um arquiteto de informações - defina regras uniformes, estrutura, lógica, estilo, coloque documentos nos espaços corretamente.
Abra a possibilidade de editar e criar documentos para os membros da equipe, concordando com as regras do jogo. Automatize essas regras ao máximo - não confie na equipe, crie modelos, identifique automaticamente o conteúdo com as tags, configure o carregamento do repositório para a base de conhecimento (a propósito, quero criar um artigo separado sobre isso).
É importante que os desenvolvedores vejam que os documentos não morrem no Wiki corporativo.
Um princípio importante: definição de feito de um documento interno, é o momento em que foram feitas alterações ou comentários , ou seja, o momento da colaboração. Este é o seu valor, eles querem gastar tempo com isso. Não complemente - significa que o processo de entrega, a implementação da pesquisa é mal organizada ou a ferramenta é inconveniente.
Os possíveis problemas dessa abordagem são o acúmulo de edições e comentários como uma bola de neve, é difícil acompanhar isso, documentos duplicados geralmente são criados.
Para impedir que isso aconteça, você pode e deve: A. Definir a equipe como um vetor, conjunto de regras e complicar o processo de não segui-las (por exemplo, ocultamos o botão Criar no Confluence e tornamos obrigatória a seleção de modelos). B. Delimitar os direitos com sabedoria e configurar convenientemente os processos de edição para os responsáveis pela arquitetura da informação.
E então o mundo perfeito virá
Os desenvolvedores não param de fazer perguntas um ao outro, incluindo estúpidas e repetitivas . Eles não aprenderão a encontrar todas as respostas na base de conhecimento por conta própria. Temos humor interno quando, devido às limitações do índice de pesquisa Confluence, os desenvolvedores não conseguem encontrar algo, me perguntam como arquiteto da informação. Chamamos isso de pesquisa baseada em Sveta.
Apesar dessas limitações, a própria estrutura da base de conhecimento, a nomeação unificada das páginas, o uso de rótulos os estimulará a pesquisar e criar conhecimento para que, por exemplo, eles não respondam a perguntas repetidas constantemente.
Outro truque que aplicamos é sempre incluir um contexto comercial nos documentos, mesmo que seja uma descrição de uma biblioteca ou classe ou uma lista de verificação para uma tarefa, é importante entender o que isso significa para o cliente.
Agora para praticar
A próxima parte será sobre "Como", quais recursos internos do Confluence (sim, usamos a pilha Atlassian) podem ser usados para implementar esses princípios.
Padrões
Criamos modelos prontos para diferentes tipos de documentos que escrevemos com mais freqüência - especificações técnicas, instruções, lista de verificação. Eles podem ser configurados no painel do espaço do administrador. São necessários modelos para que, ao criar um documento, o desenvolvedor não veja uma página em branco à sua frente, ele já tenha instruções sobre o que escrever nesta ou naquela seção. Se você deseja que documentos de um determinado tipo se encaixem em uma seção e meta-informações sejam exibidas nelas (isso é conveniente, por exemplo, para descrever os componentes de um produto complexo ou um conjunto de microsserviços de acordo com um esquema), crie um blueprint, é como um modelo na velocidade máxima.
Neles, configuramos o layout da página, os cabeçalhos, onde resta apenas substituir algumas palavras, um cabeçalho com status, imagens, tabelas, blocos de código e até variáveis.
Variáveis são elementos de conteúdo pré-configurados aos quais outro editor de documentos deve atribuir importância, por exemplo, inserir texto ou selecionar em uma lista.
Você também pode adicionar tags ao modelo com antecedência; se for um tipo restrito de documento, poderá mencionar usuários como revisores, por exemplo, se houver um fluxo de trabalho claro por nome, macro Jira e anexar um ticket da Jira. Nossa experiência mostra que até 80% das tarefas podem ser cobertas com modelos.
Layout da página
Outro elemento importante é a criação de uma página de destino bonita e compreensível no espaço da equipe. Para fazer isso, usamos o layout da página e as macros Painel, Coluna e Seção.
Abaixo está um exemplo de um de nossos espaços de equipe de desenvolvimento.
Use nomes de páginas amigáveis. Como você deve saber, o Confluence não suporta nomes de páginas idênticos no mesmo espaço. Mantenha nomes de páginas claros, como
Mau nome Python
Bom nome Python Styleguide para equipe de serviços internos
Etiquetas
O Confluence tem algumas limitações no algoritmo de pesquisa relacionado à indexação de conteúdo. E para a base de conhecimento corporativa, são precisamente as descobertas e conexões que são as questões mais prementes. Temos um artigo inteiro na base de conhecimento chamado Como vencer a Pesquisa de Confluência, se você quiser, compartilharei nos comentários.
Para superar essas limitações, usamos um sistema de etiquetas. De fato, são tags que marcam o assunto do conteúdo e por que permitem agregar o conteúdo de um assunto específico em um só lugar, na forma de um tipo de Feed RSS (macro Conteúdo por Rótulo). Então, nós configuramos índices de assuntos.
Se você já possui centenas de páginas no banco de dados, recomendamos que você comece com os seguintes exercícios:
- Veja uma lista de todos os marcadores no seguinte URL https: // <my-host-name> /labels/listlabels-alphaview.action.
- Encontre todo o conteúdo não marcado com nenhum marcador na sequência de pesquisa avançada: digite: página NOT labelText: [a TO z] NOT labelText: [0 TO 9].
O que você pode fazer agora?
- Dê aos desenvolvedores o direito de editar, mas com sabedoria.
- Pense na estrutura do espaço de comando, faça uma página de destino conveniente.
- Personalize os modelos.
- Use etiquetas.
- Vá e edite o documento de outra pessoa ou escreva um comentário, faça com que este documento funcione.