🥇Design no Confluence

Olá a todos!

Meu nome é Masha, sou engenheira de qualidade no grupo de empresas Tinkoff. O trabalho de QA envolve muitas comunicações com diferentes pessoas de diferentes equipes, e como também fui gerente e palestrante de programas educacionais, meu mapa de comunicações era o mais amplo possível. E em algum momento, eu explodi: percebi que não podia mais, não podia mais, não podia mais preencher montanhas infernais de tabelas e documentos ilegíveis.

Com certeza, cada um de vocês agora imaginou o que estou dizendo e começou a suar frio: listas de nomes sem ordem alfabética, tabelas com centenas de colunas com formatação desalinhada, tabelas com milhares de linhas, onde você precisa usar o dedo na roda do mouse para ver o cabeçalho, toneladas de páginas de instruções não numeradas, centenas de e-mails reenviados com dados que precisam ser analisados e sistematizados e colocados em tabelas igualmente ilegíveis.

E então, quando eu estava um pouco mais calma, decidi escrever este artigo. Vou falar sobre como é possível gerenciar a documentação não produtiva de forma normal (e às vezes até conveniente). Espero que o artigo se espalhe pela rede e que o nível de confusão nos departamentos adjacentes ao desenvolvimento diminua um pouco, e que as pessoas (incluindo eu) fiquem um pouquinho mais felizes.

Ferramentas

A documentação produtiva geralmente é armazenada próxima ao código, e isso é bom. Já a documentação não produtiva costuma ser armazenada em qualquer lugar. Muitas vezes, as pessoas tentam transferir informações de diferentes lugares para o Confluence, e nós não somos exceção. Então, aqui vai toda a história sobre ele.

Na verdade, o Confluence é um motor de wiki avançado. Ele permite trabalhar com dados em diferentes formatos de exibição: texto formatado, tabelas, vários tipos de diagramas. É uma ferramenta muito interessante e poderosa, mas se você não souber como usá-la, acabará com mais uma pilha de documentos ilegíveis. Vou ensinar vocês a usá-la!

Macros

Quase toda a mágica do Confluence é construída em torno de macros. Existem muitas macros, e elas podem ser combinadas entre si. Algumas são pagas e outras são gratuitas, e a seguir haverá diferentes exemplos de macros com links para a documentação correspondente.

A interface para trabalhar com macros é extremamente simples. Para adicionar uma macro, você deve clicar no sinal de mais e escolher o elemento desejado na lista.

Se o macro é autossuficiente, ou seja, não precisa de nada mais inserido dentro dele, ele parece um bloco.

Se o funcionamento do macro requer que algo seja inserido dentro dele, ele se parece com uma moldura.

Dentro de uma moldura, é possível colocar quantos outros elementos desejar, desde que haja lógica na sua pirâmide.

Cada macro tem uma pré-visualização: nela, você pode ver imediatamente se preencheu e configurou o macro corretamente.

Modelos

Além dos macros, há uma ferramenta conveniente de preenchimento automático de conteúdo — o modelo.
Os modelos podem ser usados na criação de qualquer página: basta clicar nos três pontos ao lado do botão 'Criar' e selecionar o modelo desejado.

Assim, todo o conteúdo presente no modelo será adicionado à página criada.

Qualquer um pode criar páginas a partir de modelos, mas apenas aqueles que têm permissão podem criar ou editar os próprios modelos. No modelo, é possível adicionar instruções adicionais sobre como gerenciar a página.

A Magia das Tabelas

Como técnico, eu realmente amo tabelas e consigo organizar quase qualquer informação nelas (embora isso nem sempre seja eficaz). Por si mesmas, as tabelas são claras, estruturadas, escaláveis, mágicas!

Mas até mesmo uma entidade tão maravilhosa quanto a tabela pode ser estragada. No entanto, ela pode ser usada de maneira eficaz e até melhorada. Sobre isso, falaremos a seguir.

Filtragem (plugin pago)

Qualquer tabela enorme e ilegível pode ser tornada um pouco menos imensa e um pouco mais legível através da filtragem. Para isso, pode-se usar um macro pago. ‘Filtro de Tabelas’.

Dentro desse macro, é necessário inserir a tabela (pode até ser a mais feia, o importante é engoli-la por completo). No macro, você pode escolher as colunas para filtragem através de uma lista suspensa, filtro de texto, filtro numérico e filtro por datas.

Imagine que todas as informações sobre candidatos a todas as vagas são registradas em uma lista tabular. Naturalmente, não ordenada — as pessoas não vêm a entrevistas em ordem alfabética. E você precisa entender se já entrevistou um candidato específico antes. Basta inserir essa bagunça no macro de filtro, adicionar um filtro de texto pelo sobrenome — e voilà, a informação está na sua tela.

Vale ressaltar que a filtragem de grandes tabelas pode impactar o desempenho do sistema e o tempo de carregamento das páginas. Portanto, utilizar uma grande tabela em um filtro é uma solução temporária. É melhor estabelecer um processo em que as pessoas não precisem criar tabelas enormes e ilegíveis (um exemplo desse processo será apresentado no final do artigo).

Ordenação (plugin pago)

Com a ajuda de um macro mágico ‘Filtro de Tabelas’ também é possível definir a ordenação padrão por qualquer coluna e numerar as linhas. Ou clicar em qualquer coluna da tabela que está no macro de filtro, e a ordenação acontecerá por essa coluna.

Por exemplo, você tem a mesma tabela com candidatos e precisa estimar quantas entrevistas foram realizadas em um determinado mês - ordene por data e aproveite.

Tabelas dinâmicas (plugin pago)

Agora vamos para um caso mais interessante. Imagine que sua tabela é enorme e você precisa fazer algum cálculo com ela. Claro, você pode copiar para o Excel, calcular o que precisa e reimportar os dados de volta para o Confluence. Ou você pode aplicar uma vez o macro «Tabela dinâmica» e obter o mesmo resultado, mas com a vantagem de ser atualizado.

Por exemplo: você tem uma tabela que contém dados de todos os funcionários - onde eles estão localizados e quais cargos ocupam. Para calcular quantas pessoas estão em cada cidade, você precisa selecionar no macro «Tabela dinâmica» a linha pela qual os dados serão agregados (localização) e o tipo de operação (adição).

Naturalmente, é possível agrupar por diversos critérios ao mesmo tempo; todas as opções podem ser consultadas na documentação.

Gráficos (plugin pago)

Como já mencionei, nem todos gostam de tabelas tanto quanto eu. Infelizmente, na sua maioria, os gerentes não as apreciam. Porém, todos adoram gráficos coloridos e vibrantes.
Os criadores do Confluence certamente sabiam disso (eles provavelmente também têm chefes que adoram relatórios e gráficos, o que não poderia faltar). Assim, você pode usar o macro mágico «Gráfico da tabela». Neste macro, você deve inserir a tabela dinâmica do item anterior, e voilà - seus dados cinzentos e entediantes são lindamente visualizados.

Naturalmente, há opções de configuração nesse macro também. O link para a documentação de qualquer macro pode ser encontrado no modo de edição desse macro.

Facilidade de agregação

As informações dos pontos anteriores certamente não foram uma revelação para você. Mas agora você sabe definitivamente como usar macros, e eu posso passar para a parte mais interessante do artigo.

Etiquetas

É ruim quando as pessoas guardam informações em um único artigo não estruturado ou em uma imensa tabela. Pior ainda é quando partes dessas informações não apenas estão mal organizadas, mas também espalhadas por diferentes áreas do Confluence. Felizmente, existe a possibilidade de reunir as informações dispersas em um só lugar. Para isso, é necessário usar tags (as mesmas que todos conhecem das redes sociais).

Qualquer página pode ter um número ilimitado de tags adicionadas. Se você clicar em uma tag, será direcionado a uma página de agregação, onde encontrará links para todos os materiais com essa tag, além de um conjunto de tags relacionadas. As tags relacionadas são aquelas que costumam aparecer em uma mesma página.

Propriedades das páginas

Você também pode adicionar outra macro interessante para estruturar informações à página — "Propriedades das páginas". Dentro dela, você deve inserir uma tabela de duas colunas, sendo a primeira a chave e a segunda o valor da propriedade. Além disso, a macro pode ser ocultada da página, para que não atrapalhe a leitura do conteúdo, mas a página ainda assim será marcada com as chaves necessárias.

Preste atenção no ID — é conveniente defini-lo para associar diferentes grupos de propriedades a diferentes páginas (ou até mesmo diferentes grupos de propriedades em uma única página).

Relatórios

Relatórios podem ser gerados por meio das tags. 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 por Propriedades da Página". Ela também agrega todas as páginas com um determinado conjunto de tags, mas não apenas apresenta uma lista, e sim compõe uma tabela (você percebe a conexão com o começo do artigo?), onde as colunas são as chaves das propriedades da página.

Assim, obtém-se uma tabela resumo com informações de diferentes fontes. É agradável que ela possua funções práticas: layout responsivo, ordenação por qualquer coluna. Além disso, essa tabela de relatório pode ser configurada dentro da macro.

Ao configurar, é possível remover algumas colunas do relatório, definir um estado padrão ou a quantidade de registros exibidos. Também é possível definir o ID da propriedade da página, para visualizar apenas as informações desejadas.

Por exemplo, você tem várias páginas de funcionários, e essas páginas têm um conjunto de propriedades sobre a pessoa: qual é o seu nível, onde está localizado, quando entrou na equipe e assim por diante. Essas propriedades são marcadas ID = employee_inf. E há um segundo conjunto de propriedades na mesma página, que reúne informações sobre a pessoa como parte da equipe: qual o papel que a pessoa desempenha, em que equipe está e assim por diante. Essas propriedades são marcadas ID = team_inf. Então, ao compor um relatório, você pode extrair informações de um único ID ou de ambos — como for mais conveniente.

A beleza desse approach é que cada um pode compor a tabela de informações que precisar, que não será duplicada e será atualizada quando a página principal for modificada. Por exemplo: para um líder de equipe, não importa quando seus desenvolvedores foram contratados, mas sim qual papel cada um desempenha na equipe. O líder de equipe coletará um relatório da equipe. E para o contador, não importa quem desempenha qual papel, mas as funções são importantes — ele coletará um relatório por funções. Enquanto isso, a fonte da informação não será duplicada ou movida.

O processo final

Instrução

Assim, podemos estruturar de forma bonita e agregar informações de maneira eficiente no Confluence, usando o exemplo do uso de macros. Mas, idealmente, deve-se fazer com que novas informações sejam imediatamente estruturadas e se encaixem em todos os mecanismos de agregação já utilizados.

Aqui, a combinação de macros e templates ajudará. Para forçar as pessoas a criarem novas páginas no formato desejado, pode-se usar a macro "Criar a partir de template". Ela adiciona um botão à página, que ao ser clicado cria uma nova página a partir do template que você deseja. Dessa forma, você faz com que as pessoas trabalhem imediatamente no formato que você precisa.

No template do qual você permite a criação de uma página, é necessário adicionar previamente tags, a macro "Propriedades da página" e a tabela das propriedades desejadas. Também recomendo adicionar instruções sobre quais valores devem ser preenchidos na página e os valores das propriedades.

Então, o processo final será assim:

Você cria um template para informações de certo tipo.
Nesse template, você adiciona tags e propriedades da página na macro.
Em qualquer lugar conveniente, você cria uma página raiz com um botão que, ao ser clicado, gera uma página filha a partir do modelo.
Você libera na página raiz usuários que potencialmente irão gerar as informações necessárias (de acordo com o modelo, clicando no botão).
Você coleta um relatório sobre as propriedades da página através das etiquetas que você especificou no modelo.
Você fica contente: você possui todas as informações necessárias em um formato conveniente.

Pontos críticos

Como engenheiro de qualidade, posso afirmar com segurança que nada é perfeito no mundo. Até mesmo as tabelas divinas são imperfeitas. E no processo mencionado acima, há pontos críticos.

Se você decidir mudar 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 sincronizados no relatório consolidado. Isso é triste, mas, por outro lado, força você a pensar detalhadamente na "arquitetura" do seu conjunto de informações, o que é uma tarefa bastante interessante.
Você terá que escrever uma quantidade razoável de instruções sobre como preencher as tabelas de informações e usar as etiquetas. Mas, por outro lado, você pode simplesmente enviar este artigo para todas as pessoas necessárias.

Exemplo de armazenamento de documentação não relacionada a produtos

Através do processo descrito acima, é possível organizar o armazenamento de quase qualquer informação. A beleza da abordagem é que ela é universal: quando os usuários se acostumam, eles param de gerar desordem. Além disso, um grande (mas não gratuito) ponto a favor é a possibilidade de coletar estatísticas variadas em tempo real e criar gráficos bonitos com base nelas.

Vou dar um exemplo do nosso processo de gestão de informações sobre a equipe.

Para cada pessoa na equipe, decidimos criar um cartão de funcionário. Portanto, temos um modelo segundo o qual cada novo membro cria seu cartão e gerencia nele todas as suas informações pessoais.

Como você vê, temos uma tabela abrangente de propriedades e já existem instruções sobre como manter essa página. Algumas etiquetas são preenchidas pelos próprios funcionários seguindo as instruções, no modelo estão apenas as principais: etiqueta do cartão employee-card, etiqueta da direção direction-involve e etiqueta da equipe team-qa.

Após cada um criar seu próprio cartão, obtemos uma tabela completa com informações sobre os colaboradores. Essas informações podem ser utilizadas em diferentes pontos. Os gerentes de recursos podem compilar tabelas gerais, enquanto os líderes das equipes podem criar tabelas de equipe, adicionando à seleção a tag da equipe.

Por meio das tags, é possível ver diferentes resumos, por exemplo, sobre plano-de-atualização-qa todas as tarefas de desenvolvimento de QA serão exibidas. Ao mesmo tempo, cada pessoa em seu cartão de colaborador mantém uma história importante e seu plano de desenvolvimento — criando uma página aninhada a partir do template de planos de desenvolvimento.