👨‍🚀 👩🏼‍💼 🧗🏼 Design na Confluence 🤴🏿 🐷 🦉

Olá a todos!

Meu nome é Masha, trabalho como engenheiro de garantia de qualidade no grupo de empresas Tinkoff. O trabalho de controle de qualidade envolve muita comunicação com pessoas diferentes de equipes diferentes, e eu também era gerente e conferencista de programas educacionais; portanto, meu mapa de comunicação era o mais amplo possível. E em algum momento explodi: percebi que não podia mais, não podia, não podia encher o inferno de toneladas de tabelas e documentos ilegíveis.

Certamente cada um de vocês agora imaginou o que eu estava falando e varreu em suor frio: listas de sobrenomes sem ordem alfabética, tabelas de centenas de colunas com um layout que havia se movido para fora, tabelas de milhares de linhas nas quais você precisa apagar o dedo na roda do mouse para assistir cabeçalho, toneladas de páginas de instruções não numeradas, centenas de cartas enviadas entre si com dados que precisam ser analisados e sistematizados e colocados nas mesmas tabelas ilegíveis.

E assim, quando fiquei com um pouco de frio, decidi escrever este artigo. Vou falar sobre como você normalmente (mesmo às vezes convenientemente) mantém uma variedade de documentação que não é do produto. Espero que o artigo se espalhe pela rede e o nível de aditamento nos departamentos adjacentes ao desenvolvimento diminua um pouco, e as pessoas (inclusive eu) se tornem um pouco mais felizes.

Ferramentas

A documentação do produto geralmente é mantida próxima ao código, o que é bom. E a documentação que não é do produto geralmente é armazenada em qualquer lugar. Muitas vezes, as pessoas tentam transferir informações de diferentes lugares para o Confluence, e não somos exceção. Então, toda a história adicional sobre ele.

Em geral, o Confluence é um mecanismo wiki avançado. Ele permite trabalhar com dados em diferentes tipos de exibição: texto com formatação, tabelas, diversos diagramas. Essa é uma ferramenta muito interessante e poderosa, mas se você não sabe como cozinhá-la, receberá outro despejo de documentos ilegíveis. Eu vou te ensinar como cozinhar!

Macros

Quase toda a magia do Confluence é construída em macros. Existem muitas macros e elas podem ser combinadas entre si. Eles são pagos e gratuitos, e haverá diferentes exemplos de macros com links para a documentação para eles.

A interface macro é a mais simples possível. Para adicionar uma macro, clique no sinal de mais e selecione o item desejado da lista.

Se a macro é auto-suficiente, ou seja, não requer a inserção de outra coisa dentro de si mesma, parece um bloco.

Se para a macro funcionar, você precisa colocar algo dentro dela, ela se parece com um quadro.

Ao mesmo tempo, você pode colocar quantos outros quiser dentro do quadro, se houver lógica na sua pirâmide.

Cada macro tem uma visualização: mostra imediatamente se você concluiu e configurou a macro corretamente.

Padrões

Além das macros, há uma ferramenta conveniente para pré-preencher o conteúdo - este é um modelo.
Os modelos podem ser usados ao criar qualquer página: basta clicar nos três pontos ao lado do botão "Criar" e selecionar o modelo desejado.

Todo o conteúdo do modelo será adicionado à página criada.

Qualquer pessoa pode criar páginas a partir de modelos, mas apenas aqueles que têm o direito de criar ou editar os próprios modelos. Você pode adicionar instruções adicionais ao modelo sobre como manter a página.

Magia de mesa

Na verdade, como técnico, eu amo muito as tabelas e posso incluir quase todas as informações (embora isso nem sempre seja eficaz). As mesas são claras, estruturadas, escaláveis, mágicas!

Mas mesmo uma entidade maravilhosa como uma mesa pode ser arruinada. E você pode usar e até melhorar com sucesso. Sobre isso abaixo.

Filtragem (plugin pago)

Qualquer tabela enorme ilegível pode ser um pouco menos grande e um pouco mais legível por filtragem. Para fazer isso, você pode usar a macro paga "Tabelas de filtro" .

Dentro dessa macro, você precisa colocar a mesa (você pode até a mais feia, a principal coisa é empurrá-la por inteiro). Na macro, você pode selecionar as colunas para o filtro com uma lista suspensa, um filtro de texto, um filtro numérico e um filtro por datas.

Imagine que todas as informações dos candidatos a todas as vagas sejam registradas em uma lista tabular. Naturalmente, sem classificação - as pessoas não vêm para entrevistas em ordem alfabética. E você precisa entender se você já entrevistou um candidato em particular antes. Você só precisa colocar esse inferno na macro do filtro, adicionar um filtro de texto pelo sobrenome - e pronto, as informações na tela.

É importante notar que a filtragem de tabelas enormes pode afetar o tempo de carregamento do sistema e da página; portanto, colocar uma tabela enorme no filtro é uma muleta temporária; é melhor criar um processo no qual as pessoas não precisam criar tabelas imensas (um exemplo do processo será no final do artigo).

Classificar (plugin pago)

Usando a macro mágica "Filtro de tabela", você também pode definir a classificação padrão por qualquer coluna e numerar as linhas. Ou clique em qualquer coluna da tabela exibida na macro de filtro e a classificação por essa coluna ocorrerá.

Por exemplo, você tem a mesma tabela com os candidatos e precisa descobrir quantas entrevistas foram realizadas em um mês específico - classifique por data e seja feliz.

Tabelas de resumo (plug-in pago)

Agora vamos ao caso mais interessante. Imagine que sua mesa é enorme e você precisa calcular algo a partir dela. Obviamente, você pode copiá-lo para o Excel, calcular o que precisa e fazer o upload dos dados de volta ao Confluence. Ou você pode aplicar a macro "Tabela dinâmica" uma vez e obter o mesmo resultado, mas também atualizado.

Por exemplo: você tem uma tabela na qual os dados de todos os funcionários são coletados - onde eles estão localizados geograficamente e quais posições eles ocupam. Para calcular quantas pessoas existem em cada cidade, é necessário selecionar na macro "Tabela Resumo" uma linha pela qual os dados (local) e o tipo de operação (agregação) são agregados.

Naturalmente, você pode agrupar por vários critérios ao mesmo tempo, todos os recursos podem ser encontrados na documentação .

Gráficos (plugin pago)

Como eu disse, nem todo mundo gosta de mesas tanto quanto eu. Infelizmente, a maioria deles não gosta de gerentes. Mas todo mundo adora cartelas de cores vibrantes.
Os criadores do Confluence, é claro, sabiam disso (eles provavelmente também têm um chefe que adora relatórios e gráficos, mas que sem eles). Portanto, você pode usar a macro mágica "Gráfico da tabela" . Nesta macro, você precisa colocar a tabela dinâmica do parágrafo anterior e pronto - seus dados chatos em cinza são lindamente visualizados.

Naturalmente, essa macro também possui configurações. Um link para a documentação para 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 eu posso passar para a parte mais interessante do artigo.

Tag

É ruim quando as pessoas armazenam informações em um artigo não estruturado ou em uma grande mesa. Pior ainda - quando partes dessas informações não são apenas ilegíveis, mas também espalhadas pelas extensões do Confluence. Felizmente, há a oportunidade de coletar as informações espalhadas em um só lugar. Para fazer isso, use as tags ( tags familiares a todos nas redes sociais).

Você pode adicionar qualquer número de tags a qualquer página. Se você clicar em uma tag, será direcionado para a página de agregação, onde há links para todos os materiais com essa tag, bem como com um conjunto de tags relacionadas. Tags relacionadas são aquelas frequentemente encontradas na mesma página.

Propriedades da página

Você pode adicionar outra macro interessante à página para estruturar informações - “Propriedades da página” . Dentro dela, 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 oculta da página para não interferir na leitura do conteúdo, mas ao mesmo tempo a página ainda será marcada com as teclas necessárias.

Preste atenção ao ID - é conveniente configurá-lo para travar diferentes grupos de propriedades em páginas diferentes (ou mesmo grupos de propriedades diferentes em uma página).

Relatórios

Por tags, você pode coletar relatórios. Por exemplo, a macro Relatório de Conteúdo coleta todas as páginas com um conjunto específico de tags.

Mas um relatório mais interessante é a macro "Relatório de propriedades da página" . Ele também coleta todas as páginas com um conjunto específico de rótulos, mas não apenas exibe uma lista deles, mas compila uma tabela (pegue o link para o início do artigo?). Em quais colunas são as chaves para as propriedades da página.

Acontece uma tabela resumida de informações de várias fontes. É bom ter funções convenientes: layout adaptável, classificação por qualquer coluna. Além disso, essa tabela de relatórios pode ser configurada dentro de uma 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: qual nível ele está, onde está, quando ingressou na equipe e assim por diante. Essas propriedades estão marcadas com ID = employee_inf . E há um segundo conjunto de propriedades na mesma página que coleta informações sobre a pessoa, como parte da equipe: qual papel a pessoa desempenha, em qual equipe ele está e assim por diante. Essas propriedades estão marcadas com ID = team_inf . Em seguida, ao montar o relatório, você pode exibir apenas informações sobre um ID ou apenas dois de uma vez - como é mais conveniente.

A vantagem 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: Timlidu não é importante quando seus desenvolvedores conseguiram um emprego, mas é importante qual o papel que cada um deles desempenha na equipe. O Timlid coletará um relatório sobre a equipe. E o contador não se importa com quem desempenha qual papel, mas as postagens são importantes - ele coletará um relatório sobre as postagens. Nesse caso, a fonte de informação não será duplicada ou transferida.

Processo final

Manual de instruções

Assim, podemos estruturar de maneira lindíssima e agregar informações de maneira eficiente no Confluence usando macros como exemplo. Mas, idealmente, é necessário garantir que as novas informações sejam estruturadas imediatamente e se enquadrem em todos os mecanismos de agregação já usados.

Aqui, várias macros e modelos serão úteis. Para fazer as pessoas criarem novas páginas no formato certo, 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ê está criando 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 devem preencher a página e os valores de propriedade.

Em seguida, o processo final ficará assim:

Você cria um modelo para informações de um determinado tipo.
Adicione marcas e propriedades da página na macro a este modelo.
Em qualquer local conveniente, crie uma página raiz com um botão, clicando na qual uma página filha do modelo é criada.
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).
Reúna um relatório sobre as propriedades da página através dos rótulos que você especificou no modelo.
Alegre-se: você tem todas as informações necessárias em um formato conveniente.

Rochas subaquáticas

Como engenheiro de qualidade, posso dizer com segurança que não há nada ideal no mundo. Até as mesas divinas são imperfeitas. E no processo acima, existem armadilhas.

Se você decidir alterar o nome ou a composição das propriedades da página, será necessário atualizar todos os objetos já criados para que seus dados sejam inseridos corretamente no relatório de resumo. Isso é triste, mas, por outro lado, faz você pensar na “arquitetura” do seu conjunto de informações em detalhes, o que é uma tarefa muito interessante.
Você terá que escrever uma quantidade razoável de instruções sobre como preencher tabelas de informações e usar tags. Mas, por outro lado, você pode simplesmente lançar todas as pessoas certas neste artigo.

Um exemplo de armazenamento de documentação que não é do produto

Através do processo descrito acima, você pode organizar o armazenamento de quase todas as informações. A beleza da abordagem é que ela é universal: quando os usuários se acostumam, eles param de gerar confusão. Também uma grande vantagem (mas não gratuita) é a capacidade de coletar várias estatísticas rapidamente 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. Portanto, temos um modelo segundo o qual cada nova pessoa cria esse cartão para si e mantém todas as informações pessoais nele.

Como você pode ver, temos uma tabela detalhada de propriedades e imediatamente temos instruções sobre como manter esta página. Algumas das tags são colocadas pelos próprios funcionários de acordo com as instruções, no modelo apenas as principais: tag do cartãoempregado-card , direção tag -Direção e equipa-qa tag .

Como resultado, após todos terem criado um cartão para si mesmos, é obtida uma tabela completa com informações sobre os funcionários. Esta informação pode ser usada em vários pontos. Os gerentes de recursos podem coletar tabelas gerais para si mesmos, e os líderes de equipe podem criar tabelas de equipe adicionando uma tag de equipe à seleção.

Você pode ver diferentes resumos por tags, por exemplo, por qa-upgrade-plan, todas as tarefas para o desenvolvimento do controle de qualidade serão exibidas. Ao mesmo tempo, cada pessoa em seu cartão de funcionário lidera uma história importante e seu plano de desenvolvimento - cria uma página incorporada do modelo para planos de desenvolvimento.

Conclusão

Mantenha toda a documentação para que não seja embaraçoso e os usuários não se machuquem excruciante!

Eu realmente espero que o artigo seja útil e que toda a documentação do mundo esteja em ordem.

Design na Confluence