Clique aqui para acessar a checklist de documentação concreta.
Concretude na escrita técnica comunica o que as pessoas podem ver, ouvir, cheirar, provar ou tocar, não somente o que eles podem pensar ou imaginar. Muitos assuntos técnicos são abstratos, os usuários não podem experienciá-los diretamente. As pessoas conseguem entender mais facilmente o concreto, por esta razão, escritores relacionam o abstrato ao concreto ao apresentar muitas informações conceituais.
Na imagem abaixo, temos exemplos de expressões abstratas e concretas:
Há diferentes maneiras de representar um assunto abstrato de forma concreta, como demonstra o diagrama abaixo:
Para tornar uma informação concreta, siga estas orientações:
1. Escolha exemplos que são apropriados para a audiência e assunto.
Os usuários devem conseguir entender o exemplo e aplicar em suas circunstâncias. Você pode precisar ter exemplos para diferentes níveis de conhecimento e assuntos.
Em geral, usuários precisam de exemplos quando tem pouca experiência com o assunto ou utilizam o produto seguindo estritamente as instruções.
Você pode utilizar exemplos em textos conceituas para auxiliar na definição do conceito e em tarefas podem ser utilizados para demostrar o que o usuário deve preencher ou o que esperar de resultado.
Para definir quando utilizar um exemplo aplique os critérios abaixo:
2. Use exemplos realistas, objetivos e atualizados.
Toda informação devem ser focada, objetiva, e atualizada, possuir acurácia, e ser aplicável ao cenário do usuário, conforme já citado em outros tópicos, e para exemplos aplica-se os mesmos conceitos.
3. Torne os exemplos fáceis de localizar.
Como qualquer informação, exemplos ou cenários que são difíceis de achar não ajudam o usuário, dessa forma:
- Utilize indicadores visuais para indicar onde se encontrar os exemplos: Coloque-os separado dos textos, separando em parágrafos, em listas ou outros tópicos.
- Faça os exemplo parte da interface do usuário: Coloque exemplos em hints do campos ou mensagens dos sistemas caso seja necessário.
- Deixe claro quanto o exemplo começa e quando termina.
4. Defina o contexto para exemplos
Deixe explicito o que é importante sobre o exemplo em sua introdução fornecendo o contexto, para que o usuário saiba quando aplicá-lo.
5. Relacione informação não familiar a informações familiares
Comparar informações não familiares com informação familiares facilita o aprendizado de novas informações.
Faça o uso de analogias ou similaridades para facilitar o entendimento de um conceito, quando necessário, e evite o uso de metáforas.
6. Utilize linguagem geral apropriadamente
Documentações técnicas incluem tanto linguagem geral quanto específica, no entanto, a linguagem específica deve predominar.
A forma usual para os parágrafos em escrita técnica é proceder a partir do geral para o específico (dedução).
Documentações técnicas costumam apresentar uma descrição geral ou principio e depois casos particulares ou exceções, ao invés de derivar o principio do caso particular.
O exemplo abaixo deixa mais claro essa questão:
A Info Library não impõe um limite de tamanho explícito para objetos que são acessados e suporta grandes objetos que permitem a movimentação transparente entre os servidores. No entanto, quando uma aplicação Cliente armazena um arquivo em um servidor de objeto ou recupera um arquivo de um servidor objeto, ocorre uma relação entre o tamanho do objeto que podem ser armazenados ou recuperados e os recursos (de disco e memória) disponíveis no cliente estação de trabalho. Quando um objeto é armazenado ou recuperado pelo cliente a partir do servidor de objeto, ele é construído na memória mais de uma vez, uma vez que está sendo processado por este caminho para o armazenamento de arquivos. Se um objeto é grande demais para uma dada configuração de memória disponível, o recurso do sistema necessário não está disponível para criar essas cópias. Quando isso acontece, um tempo limite ocorre no cliente.
Info Library suporta objetos de qualquer tamanho movendo-se entre os servidores. No entanto, quando um aplicativo cliente armazena um arquivo em um servidor de objeto ou recupera-o de lá, o objetos é construído na memória mais de uma vez. Se um objeto é grande demais para a memória disponível, as cópias não podem ser feitas e um tempo timeout no cliente.