Documentação FirebirdPara escritores de documentação FirebirdGuia de escrita → Outros aspectos da escrita
Firebird home Firebird home Anterior: Escrevendo seu documentoPrincipal: Documentação FirebirdAcima: Guia de escritaPróxima: Adicionando o documento ao módulo

Aspectos do processo de escrita não relacionados com o DocBook

Linguagem e estilo
Direitos Autorais
Usando os documentos do PostgreSQL

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.

Linguagem e estilo

Linguagem

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.

Estilo

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?????

Bloqueio do escritor de documentos

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):

  1. 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(...)

  2. 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).

  3. 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.

  4. 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ê.

Direitos Autorais

Respeitando os Direitos Autorais de Outros

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.

Seu direito autoral e a LDP

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.

Usando os documentos do PostgreSQL

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:

Anterior: Escrevendo seu documentoPrincipal: Documentação FirebirdAcima: Guia de escritaPróxima: Adicionando o documento ao módulo
Documentação FirebirdPara escritores de documentação FirebirdGuia de escrita → Outros aspectos da escrita