Os primeiros passos de uma iniciante escrevendo uma documentação de página
O que eu aprendi sobre esse tipo de documentação e o que eu gostaria de ter aprendido antes
Oleg Shcherba, Ouch!
Segundo Adkisson (2020), existem pelo menos 11 tipos de documentação de design, e essas estão divididas em duas categorias: documentações que têm a ver com a perspectiva da estrutura e as que têm a ver com a perspectiva de tarefa.
Modelo de objeto, arquétipos de página, estrutura de navegação, componentes padronizados, vocabulário de sistema e mapa de arquitetura correspondem a documentação da perspectiva da estrutura, visto que se relacionam com o “esqueleto” do seu projeto. Histórias de usuário, casos de uso, narrativas de cenário, diagramas de fluxo de tela e documentações de página fazem parte da perspectiva de tarefa, já que todas se relacionam com as atividades realizadas pelos usuários em determinados contextos.
De todos esses entregáveis, decidi falar um pouco sobre a minha experiência com a documentação de página, já que foi o que mais me gerou dúvidas durante esses meses como UX/UI Designer Junior na CoBlue — nunca tinha feito nada parecido antes. Mas, aprendi bastante durante esses últimos meses e pretendo compartilhar um pouco disso nas seções abaixo. Mas antes:
Documentação de página? Hã?
Oleg Shcherba, Ouch!
Para quem não sabe — assim como eu não sabia — essa documentação mostra um panorama geral das funcionalidades de uma página e dá instruções a respeito de comportamentos e microinterações. Esse tipo de documentação ajuda a mostrar aos desenvolvedores e a outros interessados no projeto como a página foi pensada, qual a lógica por trás das funções e outras informações pertinentes.
Na CoBlue, documentamos todos os projetos logo após os testes com pessoas usuárias, quando já temos uma base do que faz sentido para elas e do que não faz tanto sentido assim.
A anatomia da documentação de página na CoBlue
Oleg Shcherba, Ouch!
A verdade é só uma: o quão complexa a sua documentação será depende diretamente do tipo de projeto, de quem lerá e da sua vontade de esmiuçar todos os detalhes do seu design. Na CoBlue nós quase sempre seguimos um roteiro — acrescentamos tópicos ou retiramos dependendo da página que trabalhamos. Basicamente, nossas documentações de página contam com:
- O propósito do projeto;
- A estrutura da página;
- Detalhes, comportamentos e interações
- Style guide
- Desenvolvimento e documentação visual
Se a página passou por um processo de redesign você também pode acrescentar as principais mudanças ocorridas no projeto. Lógicas de cálculo e permissões fazem muito sentido para o contexto CoBlue, mas retirei da lista porque não faz sentido para produtos de outras empresas — mas se fizer sentido para o seu, vá em frente e acrescente esses dois tópicos no seu texto. Explico abaixo um pouquinho da essência desses tópicos.
1. Propósito do projeto
A sua página com certeza deve ter um porquê de ser e de existir. Nessa seção você pode escrever um pouco sobre isso. Não precisa ser um texto enorme: um parágrafo bem explicativo já é o suficiente para mostrar os motivos do seu projeto existir. Você pode falar um pouco sobre a importância dele para a empresa e também para a vida das pessoas usuárias.
2. Estrutura da página
Nessa seção, geralmente escrevemos onde essa página está dentro do sistema, com que outras páginas ela se relaciona e quais as implicações disso no fim das contas. Usamos uma tabela para tal e, na maioria das vezes, ela conta com links para essas outras páginas.
3. Detalhes, comportamentos e interações
Essa é a parte mais robusta da documentação de página — diria que é o coração dela. Nela, você pode explicar mais ou menos o comportamento dos elementos e componentes no projeto. Também não precisa ser um textão, mas pode apresentar o que há de mais novo acontecendo na página — um modal que surge de um lado diferente, um botão que leva a um lugar que antes não existia, entre outras coisas. Alguns exemplos — que podem parecer equações, mas não são:
Exemplo 1: Ao clicar no botão X um formulário aparecerá, da direita para a esquerda, onde o usuário terá que escrever Y informações a respeito de W.
Exemplo 2: Ao passar o mouse no elemento A, um tooltip mostrará informações a respeito do status de B.
Colocar imagens na documentação ajuda os leitores a entenderem melhor o que está sendo descrito. GIFs podem ajudar mais ainda dependendo da interação. Por isso, não tenha medo de investir neles.
4. Style Guide
O style guide — ou guia de estilos — expõe todos os elementos usados no projeto — cores, tipografia, ícones etc. Geralmente, colocar o link para style guide já é o suficiente — às vezes ele é uma página do projeto no próprio Figma — você pode ler aqui um artigo muito bacana sobre como construímos o guia de estilos da CoBlue.
5. Desenvolvimento e documentação visual
Aqui colocamos todos os protótipos e imagens relacionadas ao projeto — geralmente num link do Google Drive — que ainda não foram colocadas na documentação em si, mas que podem ajudar no desenvolvimento do projeto ou no entendimento dele por pessoas interessadas.
Nossas documentações são todas feitas no Docs, o que facilita a visualização por outros membros da equipe. Mas você pode usar outras plataformas, como o Notion ou o Whimsical — tudo depende da sua necessidade e do seu contexto.
Dicas de quem já errou
A seguir, algumas dicas para você não se perder tanto quanto eu me perdi na primeira vez que escrevi uma documentação.
- Poupe o tempo do leitor
Para quem não sabe, a pessoa que vos escreve é bibliotecária de formação, e, como qualquer bibliotecário, eu tenho gravadas todas as cinco Leis da Biblioteconomia na minha cabeça como a tabuada de 5. Uma das leis mais importante é: poupe o tempo do leitor. Mesmo se a metodologia da sua empresa não for ágil, ninguém merece ter que ler um calhamaço de texto para enfim entender a sua página. Vá direto ao ponto sempre que possível.
Por isso, é importante deixar claro aqui que, se o seu projeto é um redesign de alguma página ou feature, você talvez não precise colocar tudo o que continua o mesmo nos mínimos detalhes, mas muito provavelmente será muito importante escrever sobre o que mudou. Isso foi algo que eu fiz e que me atrasou bastante no meu último projeto: eu queria documentar tudo, 100% do que acontecia na página. Sendo que pelo menos metade da página permaneceu com o mesmo comportamento ou aparência.
2. Escreva a documentação depois dos testes de usabilidade
Parece óbvio, não é? Eu sei, cara pessoa leitora. Mas não foi para mim. Sabe quando você pensa: “Ah, quase nada vai mudar mesmo, acho que posso dar uma adiantada no processo documentando tudo”. Pura enganação. De fato, muita coisa não mudou. Mas achar as partes que mudaram no texto, mudá-las e depois deixar o texto coerente pode ser um desafio. Principalmente porque, depois de ler algumas vezes o mesmo texto, a tendência é que algumas coisas simplesmente passem despercebidas. E eu deixei, meus amigos, como eu deixei (mas, não se preocupem, está tudo certo no momento em que escrevo este texto e o motivo você saberá a seguir).
3. Tenha um companheiro de leitura
Sempre — quando eu digo sempre, é sempre mesmo — tenha alguém próximo que possa revisar o seu texto. Como dito na seção acima, às vezes você pode simplesmente estar tão imerso no seu mundinho da documentação que algumas coisas podem ser esquecidas, ou você pode ter escrito de um jeito extremamente técnico ou mesmo confuso. Por esses e outros motivos é muitíssimo importante ter alguém que possa fazer esse trabalho de revisão.
Na CoBlue, o chapter de UX/UI Design se reúne diariamente para conversar sobre os projetos em andamento e, por esse motivo, todos, apesar de estarem em projetos completamente diferentes, conseguem ter uma visão geral dos projetos um do outro. Dessa forma, é fácil entender se algo foi esquecido e se algum ponto poderia ser melhor abordado ou enfatizado.
4. Por último e mais importante: ouça as pessoas
Parece meio óbvio para um UX Designer, não é? Mas às vezes, na correria de desenvolver um projeto, as coisas podem parecer meio confusas e nem sempre você vai prestar atenção em tudo o que dizem. Quando seu líder ou seu par tiver algo para dizer, escute, preste atenção. Por mais simples que seja, isso pode contribuir muito para o andamento da documentação e do projeto em si.
Quando comecei a minha documentação, li um pouco sobre o assunto, fui atrás de informações em blogs, vídeos etc e tal. Mas nada foi mais importante do que aprender com as pessoas com quem eu trabalho — beijos para o meu querido chapter: Amanda, Luan e Sté. Aprendi muito com vocês sobre documentação e muitas outras coisas.
Bom, esse foi o meu textão — não poupei muito o seu tempo, mas talvez na próxima eu faça isso. Obrigada por chegar até aqui. Tem alguma dica sobre documentação? Comenta aqui embaixo :)
Mais sobre documentação e outras cositas más
AELA.IO. Documentação de projetos: como criar documentos em UX Design? Aela, [São Paulo], 19 nov. 2020. Disponível em: https://medium.com/aela/documenta%C3%A7%C3%A3o-de-projetos-como-criar-documentos-em-ux-design-52548106200a. Acesso em: 1 ago. 2021.
ADKISSON, Heidi.Documentar é design: como documentação leva a melhores resultados em design. Tradução de Luciano Infanti. UX Collective, [São Paulo], 19 out. 2020. Disponível em: https://brasil.uxdesign.cc/documentar-e-design-como-documentacao-leva-a-melhores-resultados-de-design-8a05d3f95ca2. Acesso em: 1 ago. 2021.
TEIXEIRA, Fabrício. A documentação de UX na era dos protótipos interativos. UX Collective, [São Paulo], 4 mar. 2015. Disponível em: https://brasil.uxdesign.cc/a-documenta%C3%A7%C3%A3o-de-ux-na-era-dos-prot%C3%B3tipos-interativos-d055edd3f34d. Acesso em: 1 ago. 2021.
FGV. Biblioteca de Brasília. As cinco Leis de Ranganathan. Disponível em: https://sistema.bibliotecas-df.fgv.br/noticias/cinco-leis-de-ranganathan. Acesso em: 20 ago. 2021.
