| Documentação Firebird → Para escritores de documentação Firebird → Guia de escrita → Outros aspectos da escrita |
|
|
|
Após a enchente de informação sobre DocBook nas seções anteriores, nós discutiremos rapidamente algums outros aspectos importantes da escrita de documentos: linguagem, estilo, e direitos autorais.
A comunidade Firebird é bem diversa, e feita de pessoas com muitas línguas-mater diferentes. Se você escrever documentação em uma linguagem outra que não a sua própria, provavelmente cometerá algums enganos. Isso não é catastrófico, mas você deve tentar reduzir o número de erros. Algumas estratégias para ajudá-lo nisso são:
Use um dicionário! Simples, efetivo e não high-tech
Quando estiver indeciso entre duas escritas de uma palavra, ou entre várias possíveis versões de uma expressão, google (procurar no site de busca Google, é um verbo criado por causa da popularidade desse site) pelas alternativas e veja suas freqüências. E siga alguns dos links resultantes da pesquisa para ver como os falantes nativos usam a palavra ou expressão.
Tenha um falante nativo para revisar seu texto e corrigí-lo onde necessário.
Não espere um Guia de Estilo aqui - eu não saberia como escrever um mesmo... Apenas algumas diretrizes e dicas:
Tente escrever em linguagem simples e quotidiana sempre que possível. Evite palavras difíceis se existem alternativas similares mais simples.
Evite frases longas (acima de 25 palavras) se puder; especialmente duas ou mais frases longas uma após a outra.
Seja cuidadoso em construções como negativos duplos ou triplos ("Eu não posso negar que não estou aborrecido") e voz passiva ("Cuidados devem ser tomados..."). Você não precisa evitá-las a todo custo, mas lembre-se que elas podem fazer a sentença mais difícil de entender. Nesse caso, use o positivo ("Estou satisfeito") e a voz ativa ("Tenha cuidado...").
Use listas para enumerar um número de items paralelos, por exemplo:
Uma coleção de sugestões e dicas.
Uma seqüência de exemplos (como este aqui).
Passos para serem seguidos num procedimento.
Soluções alternativas para um problema.
Mas se há apenas um pequeno número de itens curtos, use uma sentença simples:"Minha mãe ama três homens: John, Dick e Dave."
Não abuse dos pontos de exclamação. Nunca use múltiplas exclamações ou interrogações. Isto é irritante!!!!!! Ou você discorda?????
Algumas vezes você sabe o que deseja escrever, e tem as palavras prontas, mas não consegue iniciar a frase - você não consegue fazer isso fluir. Isso é muito frustrante e às vezes bloqueia o avança do seu texto por vários minutos. E mais frustrante de tudo isso é fato de que você sabe o que deseja passar para seus leitores, mas não parece capaz de produzi uma sentença decente. Após muitas experiências dolorosas deste tipo, eu desenvolvi a seguinte estratégia (não que eu pense que sou o primeiro):
Escreva o que você tem que dizer em sentenças soltas e grupinhos de palavras. Não se esquente com estilo, nem que isso pareça feio. Apenas escreva o que você deseja passao ao leitor, tenha certeza que está tudo lá e na ordem certa. Se, enquanto você estiver fazendo isto, você notar que não tem certeza de alguma coisa; inclua um comentário exatamente nesse ponto. Faça os comentários se destacarem do texto em volta, por exemplo <<deste jeito>> ou !DESTE OUTRO JEITO!
Isso pode resultar num texto assim:
CVS significa Sistema de Versões Concorrentes (<<verifique!>>). Propósito: gerenciamento de versões de software. Você pode usá-lo sozinho ou em um grupo. Você precisa de um cliente CVS para usá-lo. Um cliente CVS é um programa com o qual você pode acessar o repositório do CVS (<<explicar este termo?>>). Para verificar se um cliente CVS está instalado no seu systema, digite "cvs" na linha de comando. Se não está la, vá para estar URL para baixá-lo(...)
Se você tiver incluído algum comentário, resolva-os primeiro. Verifique se CVS realmente significa Sistema de Versões Concorrentes (sim, significa). Decida se você deve explicar o termo "repositório do CVS" agora (sim, deve).
Agora, trabalhe sobre o parágrafo novamente e tente fazer o texto fluir mais naturalmente sempre que puder. Muito provavelmente será bem mais fácil do que você imaginava.
Se ainda está meio estranho, não se aborreça - melhor esquisito e claro que fluindo macio e vago. Talvez você deva revisitar esta passagem mais tarde e ver se você pode fazê-la ficar melhor.
Esta abordagem funciona para mim. Se você está travado dessa maneira, tente-a; espero que funcione para você.
Quando nós escrevemos manuais, podemos consultar todo tipo de outras documentaões - e nós devemos, porque nós desejamos o melhor resultado possível. Qualquer informação que é publicamente disponível em manuais de terceiros, guias de usuário, tutoriais, etc. pode ser livremente usado nos nossos documentos, mas é importante não confundir informação com texto literal. Nós não podemos copiar e colar texto de outros trabalhos na nossa documentação, a não ser que o autor explicitamente permita-nos isso. Verifique o aviso de copyright da obra em questão; se não há nenhum, considere que a obra está automaticamente sujeita à convenção de Berne e você deve entender que é ilegal copiá-la - mesmo parcialmente. É o mesmo caso da obra disponível grátis. Não ter que pagar por um documento não significa que você pode copiar livremente partes do mesmo em uma obra sua.
Mais especificamente, a documentação beta do Interbase 6 da Borland - mesmo grátis - não fazem parte do pacote do Interbase que foi aberto em julho de 2000. Nós perguntamos à Borland diversas vezes se nós poderíamos usar esses documentos como se estivessem sob a "Licensa Pública do Interbase", mas eles sequer se deram ao trabalho de responder. Então sinta-se livre para usar essa documentação como fonte de informação, mas não copie texto diretamente dela.
Se você contribui para o projeto de documentação do Firebird, seu trabalho será incluído no repositório de código aberto no SourceForge. Em Janeiro de 2005, o time de documentação do Firebird decidiu que as documentação geradas por ele estariam sob a Licensa de Documentação Pública. Licensiar seu trabalho sob a LDP significa que você manterá o direito autoral, mas garante aos outros certos direitos:
Uso livre: todos podem usar e distribuir seu trabalho, grátis ou por dinheiro, desde que o aviso da licensa esteja intacto.
Direito de modificação: todos podem modificar e redistribuir seu trabalho, desde que as versões modificadas sejam licensiadas também pela LDP, o aviso da licensa esteja intacto, e as modificações sejam documentadas.
Trabalhos maiores: todos podem incorporar sua documentação (modificada ou não) em um trabalho maior. O trabalho maior como um todo não necessita estar licensiado pela LDP, mas os requisitos da licensa devem ser cumpridos para as partes que estão sob a LDP.
O que é tão bom a respeito da LDP é que esta provê os mesmos direitos e restrições em termos de uso de nossos documentos quanto a IPL e IDPL (licensas do código do Firebird) para o código do FIrebird. Para o texto completo da licensa, veja os links no aviso de licensa abaixo; o fonte DocBook está em src/docs/firebirddocs/licenses.xml.
PostgreSQL é outro grande banco de dados de código abreto, com (surpresa, surpresa) muitas similaridades com o Firebird, mas também muitas diferenças. Dependendo do tipo de documentação você irá escrever, pode ser beneficial basea-la no documentação já existente do PostgreSQL. Mas lembre-se: se você usar o material do PostgreSQL, você TEM que incluir o aviso de licensa deles no seu documento.
A página de documentação do PostgreSQL é aqui:
A licensa mais recente do PostgreSQL está atualmente aqui:
Uma coisa bacana sobre a documentação do PostgreSQL é que ela foi elaborada em DocBook, assim como a nossa. Porém, eles usam DocBook SGML em vez de XML, o que significa que algumas ajustes serão necessários. Os fontes em DocBook SGML podem ser encontrados aqui:
|
| Documentação Firebird → Para escritores de documentação Firebird → Guia de escrita → Outros aspectos da escrita |