manual - de - escrita - tecnica

manual - de - escrita - tecnica

(Parte 1 de 2)

Universidade Federal do Parana Departamento de Informatica

Roberto A Hexsel

Pequeno Manual da Escrita Tecnica

Curitiba, PR 2004

Pequeno Manual da Escrita Tecnica

Roberto A Hexsel

Departamento de Informatica Universidade Federal do Parana

Resumo Este texto foi escrito como uma tentativa de apontar um rumo queles que estao iniciando-se como escritores, e apontar-lhes os erros mais comuns que sao cometidos por neofitos. A pretensao e tentar reduzir a quantidade de erros cometidos pelos meus orientados, minimizando assim o tempo perdido em revisoes. Minhas razoes sao portanto puramente egoıstas, mas e provavel que o resultado seja util tambem a outras pessoas. Evidentemente, o estilo e peremptorio e bem de acordo com o espırito de um manual.

Introducao

Muito se ouve sobre a dificuldade que as pessoas tem para escrever. A dificuldade e real porque escrever demanda esforco e trabalho. Contudo, escrever e uma habilidade que se adquire com a pratica, que se aprende. O aprendizado se inicia pela leitura de muitos livros tecnicos e artigos, e progride com o exercıcio.

Escrever um texto que descreve uma descoberta cientıfica ou avanco tecnico e uma tarefa tao importante quanto o trabalho propriamente dito, cujos resultados merecem ser relatados. A tarefa principal do pesquisador e executar a pesquisa, mas esta de nada adianta se os produtos da pesquisa nao forem repassados para a comunidade. Uma das maneiras mais eficientes de distribuir os produtos e resultados das atividades de pesquisa e justamente o texto escrito.

Os objetos de pesquisa sao inerentemente complexos e sua compreensao demanda uma boa dose de esforco por parte de quem deseja compreende-los. O texto tecnico que descreve o produto da pesquisa deve portanto ser escrito de forma a minimizar o esforco do leitor. Isso e importantıssimo por conta de varios fatores, que incluem desde limitacoes do numero de paginas permitido pelo veıculo, ate diferencas de cultura tecnica entre escritores. Textos tecnicos devem ser precisos e concisos, e mesmo que estes atributos sejam frequentemente conflitantes, a precisao nao deve ser sacrificada em favor da concisao.

Varios dos pontos discutidos a seguir foram adaptados de outros documentos com recomendacoes quanto a estilo e conteudo. Dentre eles destacam-se o livro de Lamport sobre LATEX [4], e textos com recomendacoes a potenciais autores de artigos para conferencias [3, 7, 5].

O texto esta organizado como descrito a seguir. A Secao 1 contem recomendacoes gerais quanto ao projeto, conteudo e organizacao do texto. A Secao 2 aponta falhas e erros que ocorrem com mais frequencia nos textos avaliados pelo autor, enquanto que a Secao 3 contem algumas atrocidades, e indicacoes de como evita-las.

Pequeno Manual da Escrita Tecnica 2

1 Projeto do Texto

Escrever textos tecnicos e uma atividade muito trabalhosa e que demanda uma quantidade enorme de tempo e esforco mental. Reserve tempo e prepare-se com bastante antecedencia. Estude com cuidado o tipo de texto que ira produzir. Prepare de antemao todo o material necessario para ilustrar o texto, tal como graficos, figuras e bibliografia.

Defina o enfoque e a estrutura do texto. O texto e um artigo cientıfico, manual, texto informativo, ou um tutorial? Qual e o enfoque do texto? Ele e descritivo, informativo, de nıvel avancado ou introdutorio? Dependendo do enfoque, mais ou menos espaco deve ser reservado para material introdutorio.

Esboce um projeto de seu texto, determinando quais e quantas secoes o texto contera. Para cada subtıtulo, determine o conteudo e tamanho (numero de linhas ou paragrafos). As secoes devem mostrar a sequencia logica dos componentes do texto. Isso feito, escreva o esqueleto do texto.

Qualquer processador de textos decente permite a construcao de um ındice ou sumario com um mınimo de esforco. Use esta facilidade para verificar se o esqueleto de seu texto foi bem projetado, se o sequenciamento dos topicos esta adequado e se o aninhamento das secoes e sub-secoes faz sentido.

Quais serao, e onde se situarao no texto, as figuras ou graficos ou tabelas que contem as informacoes mais relevantes do trabalho? Em secoes introdutorias, use figuras e diagramas para ilustrar os conceitos e definicoes, na medida em que sao introduzidos.

Quais serao as referencias? Como regra geral, devem ser usadas referencias recentes dentre os melhores livros e periodicos na sua area de pesquisa, embora algumas das contribuicoes mais importantes possam estar em passado mais ou menos distante. Use referencias faceis de encontrar, e na medida do possıvel, evite relatorios tecnicos, e nao use publicidade. Documentos disponıveis na Internet tendem a ser efemeros, e portanto deveriam ser evitados. Se isso nao for possıvel, as referencias aqueles devem conter a data na qual o documento foi acessado.

Revise o projeto do texto.

O que o autor deseja que leitor aprenda ao ler o texto? O que o leitor aprendera no texto? As respostas a estas perguntas devem ser claramente respondidas antes de que o autor inicie a preparacao do texto.

Revise o projeto do texto. Varias vezes.

1.2 Secoes Introdutorias

Uma secao introdutoria tem a funcao indicada pelo seu nome que e introduzir o material que vai ser apresentado em mais detalhe nas secoes subsequentes. O(s) problema(s) sao descritos e contextualizados, as ideias associadas a(s) solucao(oes) sao apresentadas. Estas secoes apenas descrevem o problema e possıveis solucoes, tratando apenas do o que e do porque, e nunca do como.

Pequeno Manual da Escrita Tecnica 3

Em se tratando de artigo cientıfico ou tese, e importante ter em mente o objetivo da Introducao, que e contextualizar o problema, e mostrar porque vale a pena resolve-lo. A solucao proposta deve ser apresentada e suas qualidades relativas com relacao as demais solucoes ja publicadas devem ser enfatizadas. A Introducao deve capturar a atencao do leitor ao mostrar as boas qualidades do trabalho.

1.3 Secoes Intermediarias

Estas secoes retomam o apresentado nas secoes introdutorias e acrescentam tantos detalhes quanto necessario para a compreensao do exposto no restante do texto. Isso inclui a definicao precisa e formalizacao das ideias, conceitos e modelos empregados nas explanacoes.

As secoes iniciam pela descricao do seu conteudo (o que da secao), seguido por todas as definicoes necessarias (o que detalhado e o porque da secao), so entao seguido dos detalhes dos problema e da solucao (o como). A secao pode terminar com um paragrafo de conexao para a secao seguinte.

Se o trabalho se baseia em algum modelo conceitual, este deve ser claramente definido e suas limitacoes explicitadas. Um diagrama equivale a mil paragrafos de texto confuso. Use o diagrama como uma ferramenta: ao descreve-lo, certifique-se de que todo o texto esta coerente e que ha uma correspondencia estrita entre o texto e o conteudo do diagrama. A princıpio, quanto maior a complexidade do modelo, maior o numero de diagramas para descreve-lo.

1.4 Secoes com Resultados

Estas secoes descrevem os resultados propriamente ditos. As secoes iniciam descrevendo os experimentos, tecnicas ou teoremas e explicando por que estes sao relevantes, bem como o que se aprendeu com os experimentos ou solucoes. Os resultados sao entao apresentados e discutidos. A relevancia e originalidade devem ser enfatizados aqui, bem como possıveis limitacoes, melhorias e desenvolvimentos.

Os resultados devem ser apresentados de forma que os experimentos possam ser repetidos e verificados por outras pessoas com mesmo grau de capacitacao que o autor.

1.5 Secao Conclusiva

Descreva novamente o contexto do trabalho. Defina o problema e explique sua relevancia e grau de dificuldade da(s) solucao(oes) existente(s). Esta definicao pode ser tecnicamente densa e empregar todos os conceitos ja introduzidos. Apresente sua solucao ou resultados e discuta seus meritos e defeitos, alem de possibilidades e desenvolvimentos futuros.

Na Conclusao nunca, mas nunca mesmo, podem ser apresentadas conclusoes que nao tenham sido discutidas nas secoes anteriores. Nao podem haver surpresas na Conclusao!

Pequeno Manual da Escrita Tecnica 4

Existem duas maneiras de se escrever o resumo, antes ou depois do texto propriamente dito. No primeiro caso, inicia-se pelo resumo, que em um paragrafo aponta todos os aspectos importantes relativos ao problema e sua contextualizacao, e quanto a solucao proposta. Isso feito, o texto completo e produzido a seguir. No segundo caso, escreve-se o texto completo e seus pontos mais importantes sao entao sintetizados no paragrafo do resumo. O resumo tem a funcao de despertar a curiosidade do leitor e deve portanto ser escrito com muito cuidado.

Leitores com alguma pratica decidem se o texto completo vale a pena ser lido apos lerem o resumo, a introducao e a conclusao. Isso significa que estas secoes devem ser escritas para convencer o leitor da qualidade e originalidade do que e reportado no texto.

2 Estilo

Textos tecnicos devem ser claros, mas principal e especialmente, precisos. Isso significa que uma certa dose de repeticao e necessaria embora a qualidade lırica e a metrica fiquem um tanto prejudicadas. O objetivo principal e transmitir um certo conjunto de ideias de forma precisa, clara, concisa e sem ambiguidade.

Textos tecnicos tendem a ser enfadonhos por sua propria natureza, mas existem excecoes. Representativos dentre meus prediletos sao os livros de Halmos, Hennessy & Patterson, e Peterson & Davie [1, 2, 6].

Observe as recomendacoes ou normas quanto a tamanho dos caracteres, margens, tıtulos e secoes. Use um processador de textos que nao tenha ideias proprias sobre a formatacao do texto, ou que mude de ideia a cada secao.

Evite orfaos, que sao (a) uma unica palavra na ultima linha de um paragrafo, (b) uma unica linha no topo de uma pagina, (c) um so paragrafo em uma secao, ou (d) uma unica subsecao de uma secao. Nao separe um (sub-)tıtulo do texto que o segue porque um tıtulo no final de uma pagina deve ser seguido de algumas linhas de texto.

Toda vez que um termo tecnico for introduzido e definido, o termo deve ser enfatizado para sinalizar ao leitor quanto a sua importancia. O paragrafo acima que define “orfaos” e um exemplo desta pratica. Em geral, tipos como italico ou enfatizado tem um efeito mais agradavel do que negrito.

Graficos devem conter os nomes dos eixos, abscissas e ordenadas. Evite graficos pseudotridimensionais com colunas de 3 dimensoes aos inves de barras simples. A pseudodimensao tem somente efeito cosmetico e nao acrescenta informacao a figura. Evite graficos esparsos (poucas linhas) ou congestionados (muitas linhas).

O tıtulo de uma (sub)secao pode, ou deve, ser repetido na primeira frase da secao, ao inves de ser omitido porque estaria implıcito pela proximidade ao tıtulo.

Pequeno Manual da Escrita Tecnica 5

Segue uma lista de recomendacoes quanto a erros frequentes e alguns vıcios, tambem comuns. Os itens sao numerados para facilitar referencias a eles.

1. O texto deve ser compilavel da mesma forma que um programa: nunca use um objeto sem que ele tenha sido definido anteriormente; se necessario, faca uma referencia para uma definicao apresentada adiante.

2. Em funcao do enfoque do texto, algumas definicoes podem ser omitidas, desde que elas sejam obviamente conhecidas da grande maioria dos possıveis leitores. Na duvida, aponte para uma referencia bibliografica.

3. Nao use definicoes por exemplo, nas quais um exemplo contem a definicao de um conceito ou termo. Primeiro defina e entao de um ou mais exemplos. Note que esta e uma definicao por exemplo.

padrao Fiber Distributed Data Interface (FDDI) eA FDDI interconecta ...

4. Nunca introduza um termo pela sua abreviatura. A maneira correta e: A rede 5. Use termos e abreviaturas consistentemente ao longo de todo o texto.

6. Evite anglicismos. Use uma expressao que melhor traduza O SENTIDO da expressao em Ingles e cite o termo original entre parenteses, entre aspas ou em italico (in English ou “in English”).

7. Nomes proprios, em geral, nao necessitam ser traduzidos (protocolos, interfaces padronizadas, etc).

8. Evite frases de aluno de primeiro grau, muito curtas ou infinitamente longas, e use vocabulario de adulto.

9. O estilo do Hino Nacional e aceitavel em poesia mas e ininteligıvel para uma parcela enorme da populacao, e portanto nao deve ser usado em textos tecnicos de Computacao. Geralmente, frases no estilo do Hino Nacional decorrem da confusao do autor enquanto as elabora, quando novas ideias lhe ocorrem e sao imediatamente inseridas no texto. O indefeso leitor e entao obrigado a tentar seguir o tortuoso fluxo de ideias do autor.

10. Como regra geral, textos tecnicos devem ser escritos na voz passiva e no presente.

Voz passiva: O arquivo deve conter as seguintes informacoes...

O programa efetua as operacoes na ordem especificada em... A implementacao do protocolo examina os campos da mensagem e entao...

Voz ativa: Devemos colocar as seguintes informacoes no arquivo...

As operacoes deverao ser efetuadas pelo programa... O protocolo devera examinar...

1. Ao inserir referencias bibliograficas no texto, sempre que possıvel tente colocar a citacao [Ruim00] em um ponto da frase que nao interrompa o fluxo do texto [Bom00]. Na frase anterior, a primeira citacao atrapalha a leitura e acrescenta pouco conteudo semantico. Em geral, e melhor empurrar a citacao para o final da frase onde ela atrapalhara menos, embora isso nem sempre seja possıvel. Se a citacao causar dificuldade de compreensao da frase, ela deve ser movida para um ponto no qual atrapalhe menos, mas sem desvincular a ideia de seu autor.

Pequeno Manual da Escrita Tecnica 6

12. Ao descrever um programa, algoritmo ou metodo, tome muito cuidado para manter claramente separada a parte que descreve o que da parte que descreve como. Primeiro explique claramente “o que faz” sem nenhuma referencia a implementacao. Somente apos a descricao “do que” e que se pode mostrar “como e feito”.

Se seu texto fala sobre Lex e Yacc, por exemplo, a descricao deve iniciar com (a) “compilador de compiladores”, (b) analise e sıntese de codigo, (c) como Lex e Yacc se relacionam, (d) o que Lex faz, (e) o que Yacc faz, (f) como os dois sao usados na sua aplicacao. A parte mais importante e obviamente (f). Seu esforco ao escrever esta parte, e o do leitor ao ler, sera muito menor se as partes introdutorias [(a) ate (e)] estiverem bem estruturadas e contiverem todas as definicoes necessarias.

13. Na medida do possıvel, evite listas iniciadas com dois pontos. Contra exemplo: uma coisa, outra coisa, uma terceira coisa. Se a lista e realmente necessaria, enumere os itens: (a) uma coisa, (b) outra coisa, e (c) ultima coisa.

Se for necessario empregar uma lista de itens (“buletada”), os itens deveriam ficar todos na mesma pagina, e cada item deve ocupar uma linha. Se os itens forem longos, possivelmente uma separacao em varios paragrafos resulta em layout que e visualmente mais agradavel. Note que esta lista e um contra exemplo.

IMPORTANTE Apos escrever cada paragrafo, volte atras e re-leia em voz alta o que escreveu. Preste atencao no que voce fala e observe se as sentencas fazem sentido. Apos escrever cada secao, volte atras e verifique o encadeamento das ideias e descricoes. Se encontrar alguma frase solta, ou acrescente mais texto para contextualiza-la, ou mova-a para o lugar apropriado. /dev/null geralmente e um bom lugar para prender ideias soltas.

(Parte 1 de 2)

Comentários