Desenvolvimento

Ξ 4 comentários

Deixe de lado o óbvio

publicado por Sarah Siqueira

Como documentadora eu ouço muito a célebre frase “Pra quê? Ninguém lê o que vocês escrevem mesmo…”. Levo na brincadeira, dou risada junto. Mas é claro que eu sei que a realidade é essa mesmo – quase ninguém lê manual… até a hora que precisamos resolver um problema. E, nesse momento, eu faço questão de fazer a diferença para o meu cliente.

Nesse sentido, tento sempre não documentar o óbvio, fugir do “romanceamento” e ir direto ao ponto, onde a ferida dói. É muito mais difícil documentar os processos complexos, e é justamente por isso que a maioria dos manuais se mantém no “arroz com feijão”.

Ao invés disso, faz-se do manual técnico uma seqüência de informações óbvias, sem objetivo de negócios e extremamente cansativas de se ler. Literalmente chamam o usuário de imbecil e, na hora que ele mais precisa, o deixam na mão. Quantas vezes você precisou saber algo numa ferramenta, entrou no help, fez sua busca, mas só achou aquilo que você já sabia, que estava “na cara”?

Pessoas lindas do meu Brasil varonil, aprendam: não documentem o óbvio! Não digam ao usuário aquilo que ele já está vendo na interface gráfica do seu produto. A célebre frase “Clique no botão X. A janela XYZ abre.” é a coisa mais esdrúxula possível e, no entanto, 9 em cada 10 manuais seguem este padrão.

Lembrem-se que, geralmente, seu usuário consulta o manual ou o help quando ele está usando a ferramenta. Então, quando ele clicar no botão X, a janela estará lá! Ou seja, são 4, 5 ou 10 palavras a mais que você poderia ter poupado seu usuário de ler. E mais – se você implementar e traduzir para 10 línguas, serão 40, 50 ou 100 palavras a menos no seu custo de produção. E se você multiplicar isso por todas as vezes que essa frase foi incluída na sua documentação… bom, vocês entenderam onde tudo isso vai dar.

Então a dica aqui é: parem de documentar o óbvio! Antes disso, analisem o conteúdo daquilo que será aresentado ao usuário. As célebres perguntinhas “who – what – when – how – why?” devem estar presentes no seu planejamento de documentação:

Quem é o seu usuário? É o programador, o administrador de banco de dados, o digitador? Qual o nível de experiência e de intimidade desse usuário com o mundo tecnológico?

Do que ele precisa? Ele precisa que você o ensine como ligar o computador? Precisa que você o diga como e onde entrar com usuário e senha no sistema? Ou precisa que você lhe dê opções de parâmetros que o ajudem a melhorar seu trabalho e performance?

Quando e como ele precisa dessa informação? Ele fica online e poderá buscá-la na internet? Você deverá fornecê-la em arquivo para que ele possa acessá-la offline? Ele vai precisar dela antes da instalação ou mesmo durante o processo, quando não poderá acessá-la na tela, e portanto deverá fornecê-la em PDF?

Porque ele precisa dessa informação? É uma questão de negócios? É puramente técnico, para melhoria de performance ou debugging? Ele precisa resolver um erro que já aconteceu? Ou ele está tentando prevenir uma situação antes que ela ocorra?

Se o seu time de documentação mantiver essas questões em mente, tenha certeza, seu usuário vai continuar não lendo seus manuais. Mas, quando ele precisar deles, terá uma grata surpresa!

Autor

Sou pós-graduada pela FGV em Gerência de TI. Já fui programadora, tradutora, revisora, e atualmente sou redatora técnica há mais de 11 anos. Aprendi inglês muito nova, e descobri a redação técnica meio que por acaso, através de um anúncio de multinacional que precisava de alguém que escrevesse bem em português e inglês e tivesse disponibilidade para viagens. Lá trabalhei por 7 anos, viajei por todos os continentes, aprimorei técnicas, e entrei em contato mais profundo com o ciclo de vida do desenvolvimento de software no Brasil. Hoje sou líder de desenvolvimento de informações na IBM, onde planejo os projetos de documentação do produto sob minha responsabilidde, desenvolvo conteúdo, reviso materiais, dou treinamentos, mentorizo equipes mais novas e auxilio no processo de globalização e de teste da interface com os usuários finais. Espero trazer a vocês bons insights sobre o mundo da documentação em TI.

Sarah Siqueira

Comentários

4 Comments

  • Boa tarde, Sarah!

    Excelente post sobre “boas práticas” de documentação. Trabalho com redação técnica de softwares há pouco mais de 6 anos (manuais, apostilas, how to, dentre outros) e, assim como tua experiência, também caí de pára-quedas nesta área.
    Chega ser um alívio encontrar alguém que fale a mesma linguagem que eu! =) Conheço apenas um ou dois profissionais de documentação.

    Concordo com tuas colocações no post. Conhecendo nosso público-alvo, basta direcionar a documentação para o perfil encontrado. Infelizmente ainda existem muitos gerentes, coordenadores e diretores que exigem minúcias, tudo devidamente explicadinho e mastigadinho (“Clique em Next, Next, Next, Confirm e Close”). Por causa disso, admito que muitos dos meus manuais foram escritos para aprendizes, e não para profissionais acostumados com os conceitos do dia-a-dia.

    Além de gerar uma carga de trabalho cansativa e enfadonha, o nível de detalhamento faz com que tenhamos aquele sentimento de escrever, escrever, escrever e não transmitir nenhuma informação ou conhecimento.

    A frase “ninguém lê manuais” é uma triste realidade. Ruim com manual, pior sem.

    Espero ler mais posts relacionados!
    Abraços,
    Rodrigo

    • Rodrigo, você não está só neste barco, acredite. No laboratório de software da IBM, somos 4, contando comigo mesma… mas, devo te dizer que é isso. Eu também não tenho outros contatos que sejam documentadores… rs…
      Mas agora que o Augusto me deu essa oportunidade, eu vou sim, fazer barulho!
      Venha sempre, visite, comente. Ponha no seu mural, mostre pra família. É assim que nós vamos criar uma cultura diferente sobre nosso trabalho… e daí quem sabe seu gerente não venha a compreender que documentar não significa descrever tudo aquilo que está na tela não é mesmo?
      Ah, e por favor, entre em contato sempre que necessário. 😉

      Um abraço,
      Sarah

  • Boa tarde Sarah,
    Ótimo post…

    Sou programador, e acabei adquirindo o hábito de ler manuais e layouts exatamente por não ler no início de um projeto e sempre perder um certo tempo, voltando e tendo que procurar alguma coisa nele. ( mas confesso que ainda é muito difícil ler as primeiras páginas, pois são sempre iguais…rs )
    E pra ser sincero, isso gerava um atraso muito grande na entrega do projeto.

    O Rodrigo disse tudo nessa frase:
    “Ruim com manual, pior sem.”

    Aproveitando…
    Você teria alguma documentação de exemplo, dessas que você postou ?

    Abraços…

    • Oi Haroldo,

      Os centros de informação do pacote MAXIMO, da IBM, são um bom exemplo. No entanto, eles são somente uma ponta do processo inteiro de documentação do produto. A outra ponta está no próprio produto, distribuído como field helps, help grids, mensagens de erro, e os próprios nomes de campos, telas, seções, tabelas, etc.
      No caso do MAXIMO, estes elementos, na tela, já estão documentados. Quando o usuário precisa de informações mais detalhadas, ele é roteado, através de um click num botão, diretamente para o tópico referente a informação que precisa, dentro do centro de infromações.
      O link externo é este: https://www.ibm.com/developerworks/wikis/display/tivolidoccentral/IBM+Maximo+Asset+Management. Você encontrará os links para as várias versões disponíveis. As versões 7.5 e 7.5.0.1 já funcionam da maneira como te descrevi. Vale a pena dar uma fuçada.
      Boa leitura! 😉

You must be logged in to post a comment.

Busca

Patrocínio

Publicidade



Siga-nos!

Newsletter: Inscreva-se

Para se inscrever em nossa newsletter preencha o formulário.

Artigos Recentes