DEAITOOLS-249 Template para documentação de spikes

Introdução

Este é um template para documentar spikes, criado devido uma necessidade identificada na equipe T-TALK, mas que pode ser utilizado por outras equipes que assim desejarem.

A pessoa que for documentar um estudo pode copiar esta página, através da opção disponível no canto superior direito da página (procure por ... ).

Após realizada a cópia, deve-se editar o título da página e as datas informadas ao lado e todo o resto, aproveitando conteúdos e macros que julgar úteis.

Desenvolvimento

Nesta parte do template demonstraremos o uso de algumas macros e recursos do TDN para incrementar o resultado final.

Títulos

Utilize os estilos de texto da barra de ferramentas. Evite fazer títulos usando negrito e alterando o tamanho da fonte. Se fizer desta forma, o título não aparecerá no índice. 

Veja, por exemplo, o texto abaixo. Ele parece um título, mas não é. (Confere ali no índice).

Título falso

Listas numeradas e marcadores

Este recurso é interessante para sequenciar etapas ou enumerar opções. Para utilizá-los, basta clicar no botão correspondente na barra de ferramentas acima.

Se digitar um "*" no início da linha e der um TAB, uma lista com marcadores será iniciada. Para inserir o próximo item da lista, basta dar ENTER ao final. Para encerrar a lista, dê mais um ENTER.

• Lista com marcadores são legais.
• Organizam as ideias.
• Dão destaque a um grupo delas.

Para listas numeradas, a ideia é a mesma:

1. Digite o número "1" seguido de um ".".
2. Dê um TAB.
3. A linha se transforma em uma lista numerada.
4. Para ir para o próximo número, dê ENTER ao final da linha.

Para sair da lista numerada, dê mais um ENTER.

Tabelas

Para incluir uma tabela no texto, basta clicar no botão correspondente, na barra de ferramentas situada no topo da página sendo editada. Clicando no botão e percorrendo o mouse sobre o grid é possível selecionar o número de linhas e colunas da tabela. Pressionando SHIFT durante a seleção das linhas e colunas, a tabela será criada sem cabeçalho.

Com cabeçalho

Sem cabeçalho

Para incluir ou eliminar linhas e colunas na tabela, basta utilizar os botões correspondentes da barra de ferramentas de tabela, que é habilitada quando se clica dentro de uma célula.

Imagens e links

Para inseri-los, utilizar os botões disponíveis na barra de ferramentas. Imagens e links podem ser incluídos usando o teclado também. Para imagens, utilize CTRL-M. Para links, selecione um texto e utilize a combinação de teclas CTRL-K.

Figura 1 - Imagem do Spike (quem assistiu Tom e Jerry lembra...)

Exemplo de link: Para mais informações sobre spikes no contexto de metodologia ágil, clique aqui.

Caixas de informação, nota e aviso

Issue do JIRA

Para incluir uma referência à uma ou mais issues do JIRA (como foi feito no canto superior direito deste documento), utilize a macro "Filtro/ocorrência JIRA", no botão "inserir mais conteúdo".

Na tela que se abre, pode-se pesquisar por um código de issue ou ir direto para a opção "Visualizado recentemente". Encontrando a issue desejada, clique no botão "Inserir".

Código fonte

Para mostrar código-fonte num documento, usamos a macro "Bloco de código". Para inserí-la, utilize o botão "+" (inserir mais conteúdo) e escolha "Outras macros", digitando por "código" na caixa de pesquisa.

package com.totvs.ttalk.guides.spike;

public class Test {
	public static void main(String[] args) {
		System.out.println("Hello, world!");
	}
}

Há várias linguagens e formatos para utilizar. Certamente, um deles vai te atender (OK, Progress e ADVPL não tem, mas pode usar um que fique parecido...  )

Diagramas

Para inserir diagramas no documento, pode-se utilizar a macro "draw.io diagram", disponível na lista de macros, quando se clica no botão "inserir mais conteúdo".

Você poderá escolher de um dos templates disponíveis na ferramenta, ou criar seu próprio diagrama. O Draw.io é muito bom para diagramas e tem vários templates. Vale a pena estudá-lo.

Labels

Labels ou rótulos não são elementos que impactam diretamente na apresentação do documento, mas permitem sua rápida localização pela engine de pesquisa do TDN.

Elas podem ser acrescentadas ao documento a qualquer tempo. Quando em modo de edição, podem ser adicionadas clicando no botão situado no topo da página, ao lado do link contendo o caminho até a página sendo editada. Curiosamente, o botão se parece com uma etiqueta (label, em inglês).

Além das palavras "spike" e "estudo", sugere-se colocar como labels a issue do JIRA (ex: deaitools-249) e outras palavras que tenham a ver com o tema do spike. 

Conclusões

O objetivo deste template é disponibilizar uma base para se documentar um spike de maneira organizada e consistente. Não é nossa pretensão tornar este template um modelo padrão para toda a empresa, mas se ele for útil e servir de inspiração para outras áreas, será para nós uma grande satisfação.

Também não é intenção deste documento esgotar todas as possibilidades de formatação e recursos do Confluence. Quem utilizar este documento como base, sinta-se livre para agregar mais recursos.

Referências consultadas

Nesta parte do template, lembre-se de incluir links e referências para os materiais que serviram de base para o seu estudo.