Olá a todos!
Meu nome é Masha, trabalho como engenheira de garantia de qualidade no grupo de empresas Tinkoff. O trabalho de controle de qualidade envolve muita comunicação com diferentes pessoas de diferentes equipes, e também fui gerente e palestrante de programas educacionais, então meu mapa de comunicação foi o mais amplo possível. E em algum momento explodi: percebi que não posso mais, não posso, não posso mais preencher toneladas infernais de tabelas e documentos ilegíveis.
Certamente cada um de vocês agora imaginou do que estou falando e começou a suar frio: listas de sobrenomes sem ordem alfabética, tabelas com centenas de colunas com layout desleixado, tabelas com milhares de linhas nas quais você precisa apagar o dedo na roda do mouse para olhar o título, toneladas de páginas de instruções não numeradas, centenas de cartas enviadas umas às outras com dados que precisam ser analisados e sistematizados e enfiados nas mesmas tabelas ilegíveis.
E assim, quando esfriei um pouco, resolvi escrever este artigo. Falarei sobre como você pode normalmente (mesmo às vezes convenientemente) manter uma variedade de documentação não relacionada ao produto. Espero que o artigo se espalhe pela rede e o nível de inferno nos departamentos adjacentes ao desenvolvimento caia pelo menos um pouco, e as pessoas (inclusive eu) fiquem um pouco mais felizes.
Ferramentas
A documentação do produto geralmente é mantida junto com o código, o que é bom. E a documentação não relacionada ao produto geralmente é armazenada em qualquer lugar. Frequentemente, as pessoas tentam trazer informações de diferentes lugares para o Confluence, e nós não somos exceção. Então o resto da história é sobre ele.
Em geral, o Confluence é um mecanismo de wiki avançado. Permite trabalhar com dados em diferentes tipos de exibição: texto com formatação, tabelas, gráficos diversos. Esta é uma ferramenta muito interessante e poderosa, mas se você não souber cozinhá-la, obterá outro despejo de documentos ilegíveis. Eu vou te ensinar a cozinhar!
macros
Quase toda a magia do Confluence é construída em torno de macros. Existem muitas macros e elas podem ser combinadas entre si. Eles são pagos e gratuitos, além disso, haverá vários exemplos de macros com links para a documentação deles.
A interface para trabalhar com macros é a mais simples possível. Para adicionar uma macro, você precisa clicar no sinal de mais e selecionar o elemento desejado na lista.
Se a macro for autossuficiente, ou seja, não requer a inserção de algo mais dentro de si, ela se parece com um bloco.
Se uma macro precisa de algo dentro dela para funcionar, ela se parece com uma caixa.
Ao mesmo tempo, você pode colocar quantos quiser dentro de um quadro, desde que haja lógica em sua pirâmide.
Cada macro tem uma visualização: mostra imediatamente se você preencheu e configurou a macro corretamente.
templates
Além das macros, existe uma ferramenta conveniente para pré-preencher o conteúdo - este é um modelo.
Os templates podem ser usados na hora de criar qualquer página: basta clicar nos três pontinhos ao lado do botão "Criar" e selecionar o template desejado.
Em seguida, todo o conteúdo que está no modelo será adicionado à página criada.
Qualquer pessoa pode criar páginas a partir de modelos, mas apenas aqueles que têm direitos para criar ou editar modelos podem criar páginas. Você pode adicionar instruções adicionais ao modelo sobre como a página deve ser mantida.
Mesa Mágica
Na verdade, como técnico, adoro tabelas e posso agrupar quase qualquer informação nelas (embora isso nem sempre seja eficaz). As próprias tabelas são claras, estruturadas, escaláveis, mágicas!
Mas mesmo uma entidade tão maravilhosa como uma mesa pode ser estragada. E pode ser usado com sucesso e até melhorado. Mais sobre isso abaixo.
Filtragem (plug-in pago)
Qualquer tabela grande e ilegível pode se tornar um pouco menos grande e um pouco mais legível usando filtragem. Para fazer isso, você pode usar uma macro paga .
Dentro dessa macro, você precisa empurrar uma mesa (mesmo a mais feia é possível, o principal é empurrá-la inteira). Na macro, você pode selecionar colunas para filtro suspenso, filtro de texto, numérico e filtro de data.
Imagine que todas as informações sobre os candidatos para todas as vagas sejam registradas em uma lista tabular. Naturalmente, não classificado - as pessoas não vêm às entrevistas em ordem alfabética. E você precisa entender se já entrevistou um candidato específico antes. Você só precisa colocar esse inferno em uma macro de filtro, adicionar um filtro de texto por sobrenome - e pronto, as informações estão na sua tela.
Vale ressaltar que filtrar tabelas enormes pode afetar o desempenho do sistema e o tempo de carregamento da página, então colocar uma tabela enorme no filtro é uma muleta temporária, é melhor construir um processo em que as pessoas não tenham que criar tabelas enormes ilegíveis (uma exemplo do processo estará no final do artigo).
Classificação (plug-in pago)
Com macro mágica você também pode definir a classificação padrão em qualquer coluna e numerar as linhas. Ou clique em qualquer coluna da tabela colocada na macro de filtro e a classificação por esta coluna ocorrerá.
Por exemplo, você tem a mesma mesa com os candidatos e precisa descobrir quantas entrevistas foram realizadas em um determinado mês - classifique por data e alegre-se.
Tabelas dinâmicas (plug-in pago)
Agora vamos passar para um caso mais interessante. Imagine que sua mesa é enorme e você precisa calcular algo nela. Claro, você pode copiá-lo para o Excel, calcular o que precisa e carregar os dados de volta para o Confluence. Você pode aplicar uma macro uma vez? e obter o mesmo resultado, apenas atualizado.
Por exemplo: você tem uma tabela que contém os dados de todos os funcionários - onde estão localizados geograficamente e quais os cargos que ocupam. Para calcular quantas pessoas existem em cada cidade, é necessário selecionar na macro "Tabela Dinâmica" a linha pela qual os dados são agregados (localização) e o tipo de operação (adição).
Naturalmente, você pode agrupar de acordo com vários critérios ao mesmo tempo, pode ver todas as possibilidades .
Gráficos (plug-in pago)
Como eu disse, nem todo mundo ama mesas tanto quanto eu. Infelizmente, a maioria dos gerentes não gosta deles. Mas todo mundo adora cartelas de cores brilhantes.
Os criadores do Confluence certamente sabiam disso (com certeza eles também têm chefes que adoram relatórios e gráficos, onde estariam sem isso). Portanto, você pode usar a macro mágica . Nesta macro, você precisa colocar a tabela dinâmica do parágrafo anterior e pronto - seus dados cinza chatos são lindamente visualizados.
Naturalmente, esta macro também possui configurações. Um link para a documentação de qualquer macro pode ser encontrado no modo de edição dessa macro.
Facilidade de agregação
As informações dos parágrafos anteriores provavelmente não foram uma revelação para você. Mas agora você definitivamente sabe como usar macros e posso passar para a parte mais interessante do artigo.
etiquetas
É ruim quando as pessoas armazenam informações em um artigo não estruturado ou em uma tabela enorme. Pior ainda é quando partes dessas informações não são apenas ilegíveis, mas também espalhadas pelas extensões do Confluence. Felizmente, é possível coletar informações dispersas em um só lugar. Para isso você precisa usar (tags familiares a todos nas redes sociais).
Qualquer número de tags pode ser adicionado a qualquer página. Clicar em uma tag levará você a uma página de agregação com links para todo o conteúdo com essa tag, bem como um conjunto de tags relacionadas. Tags relacionadas são aquelas que aparecem frequentemente na mesma página.
Propriedades da página
Você pode adicionar outra macro interessante à página para estruturar informações - . Dentro dele, você precisa enviar uma tabela de duas colunas, a primeira será a chave e a segunda será o valor da propriedade. Além disso, a macro pode ser ocultada da página para não atrapalhar a leitura do conteúdo, mas a página ainda estará marcada com as chaves necessárias.
Preste atenção ao ID - é conveniente configurá-lo para pendurar diferentes grupos de propriedades em páginas diferentes (ou mesmo grupos diferentes de propriedades em uma página).
relatórios
Por tags, você pode coletar relatórios. Por exemplo, macro coleta todas as páginas com um determinado conjunto de tags.
Mas um relatório mais interessante é uma macro . Ele também coleta todas as páginas com um determinado conjunto de tags, mas não apenas as lista, mas compila uma tabela (você entendeu a conexão com o início do artigo?), Em que as colunas são as chaves das propriedades da página.
Acontece uma tabela de resumo de informações de diferentes fontes. É bom que tenha recursos convenientes: layout adaptável, classificação por qualquer coluna. Além disso, essa tabela de relatórios pode ser configurada dentro da macro.
Ao configurar, você pode remover algumas colunas do relatório, definir o estado padrão ou o número de registros exibidos. Você também pode definir o ID da propriedade da página para ver apenas as informações necessárias.
Por exemplo, você tem muitas páginas de funcionários, essas páginas têm um conjunto de propriedades sobre uma pessoa: em que nível ela está, onde está, quando ingressou na equipe e assim por diante. Essas propriedades são marcadas id = funcionário_inf. E há um segundo conjunto de propriedades na mesma página, que contém informações sobre uma pessoa como parte de uma equipe: qual função a pessoa desempenha, em que equipe ela está e assim por diante. Essas propriedades são marcadas ID = equipe_inf. Então, ao compilar um relatório, você pode exibir apenas as informações de um ID ou dois de uma vez - o que for mais conveniente.
A beleza dessa abordagem é que todos podem coletar a tabela de informações de que precisam, que não duplicará nada e será atualizada quando a página principal for atualizada. Por exemplo: um líder de equipe não se importa quando seus desenvolvedores conseguem um emprego, mas é importante qual o papel que cada um deles desempenha na equipe. O líder da equipe coletará um relatório sobre a equipe. E o contador não se importa com quem desempenha qual função, mas os cargos são importantes - ele fará um relatório sobre os cargos. Neste caso, a fonte de informação não será duplicada ou transferida.
processo final
Instrução
Assim, podemos estruturar lindamente e agregar informações de forma eficaz no Confluence usando macros como exemplo. Mas, idealmente, você precisa garantir que as novas informações sejam imediatamente estruturadas e cheguem a todos os mecanismos de agregação já em uso.
Aqui, um monte de macros e modelos virão em socorro. Para que as pessoas criem novas páginas no formato correto, você pode usar a macro Criar a partir do modelo. Ele adiciona um botão à página, clicando no qual uma nova página é criada a partir do modelo que você precisa. Assim você faz as pessoas trabalharem imediatamente no formato que você precisa.
No modelo a partir do qual você permite criar uma página, você precisa adicionar rótulos, a macro "Propriedades da página" e uma tabela das propriedades necessárias com antecedência. Também recomendo adicionar instruções sobre quais valores preencher a página e valores de propriedade.
Então o processo final ficará assim:
- Você está criando um modelo para um tipo específico de informação.
- Neste modelo, adicione rótulos e propriedades de página em uma macro.
- Em qualquer local conveniente, crie uma página raiz com um botão, clicando no qual uma página filho é criada a partir do modelo.
- Inicie na página raiz dos usuários que potencialmente gerarão as informações necessárias (de acordo com o modelo desejado, clicando no botão).
- Colete você mesmo um relatório sobre as propriedades da página por meio das tags que você especificou no modelo.
- Alegre-se: você tem todas as informações de que precisa em um formato conveniente.
Armadilhas
Como engenheiro de qualidade, posso dizer com segurança que não há nada perfeito no mundo. Mesmo as mesas divinas são imperfeitas. E há armadilhas no processo acima.
- Se você decidir alterar os nomes ou a composição das propriedades da página, terá que atualizar todos os objetos já criados para que seus dados sejam corretamente inseridos no relatório de resumo. Isso é triste, mas, por outro lado, obriga você a pensar detalhadamente sobre a "arquitetura" do seu conjunto de informações, o que é uma tarefa muito interessante.
- Você terá que escrever uma quantidade decente de instruções sobre como preencher as tabelas de informações e usar as tags. Mas, por outro lado, você pode simplesmente lançar este artigo para as pessoas certas.
Um exemplo de armazenamento de documentação não relacionada ao produto
Por meio do processo descrito acima, você pode organizar o armazenamento de quase todas as informações. A beleza da abordagem é que ela é universal: uma vez que os usuários se acostumam com ela, eles param de fazer bagunça. Também uma grande vantagem (mas não gratuita) é a capacidade de coletar várias estatísticas em tempo real e desenhar belos diagramas nela.
Vou dar um exemplo do nosso processo de manutenção de informações sobre a equipe.
Para cada pessoa da equipe, decidimos criar um cartão de funcionário. Assim, temos um modelo segundo o qual cada nova pessoa cria este cartão para si e guarda nele todas as suas informações pessoais.
Como você pode ver, temos uma tabela detalhada de propriedades e imediatamente temos instruções sobre como manter esta página. Algumas das etiquetas são colocadas pelos próprios funcionários de acordo com as instruções, no modelo apenas as principais: a etiqueta do cartão cartão de empregado, marca de direção direção-envolver e etiqueta de comando controle de qualidade da equipe.
Como resultado, após cada um criar um cartão para si, obtém-se uma tabela completa com informações sobre os funcionários. Esta informação pode ser usada em diferentes pontos. Os gerentes de recursos podem coletar tabelas gerais para si mesmos e os líderes de equipe podem coletar tabelas de comando adicionando uma tag de equipe à seleção.
Por tags, você pode ver diferentes resumos, por exemplo, por plano de atualização de controle de qualidade todas as tarefas para desenvolvimento de QA serão exibidas. Ao mesmo tempo, cada pessoa em seu cartão de funcionário mantém uma história importante e seu próprio plano de desenvolvimento - ele cria uma página aninhada a partir do modelo de planos de desenvolvimento.
Conclusão
Guarde qualquer documentação de forma que você não se envergonhe dela e os usuários não se machuquem terrivelmente!
Eu realmente espero que o artigo seja útil e a ordem chegue em toda a documentação do mundo.
Fonte: habr.com