Olá, achei que valia compartilhar aqui também, embora esteja muito ausente da comunidade FreeBSD e PostgreSQL.
Obs: já achei erros de português, podem corrigir, mas já estou me adiantando a isso, o que realmente quero são idéias! ---------- Mensagem encaminhada ---------- De: Pablo Sánchez <[email protected]> Data: 7 de setembro de 2011 23:39 Assunto: How-to write technical articles (Como escrever artigos técnicos) Para: Projeto Software Livre Distrito Federal < [email protected]>, [email protected] Caros, Estou escrevendo este texto a fim de ajudar no que eu mesmo propus: eliminar o conhecimento arcaico de forma a manter sempre atualizadas todas as comunidades de TI. Sugestões são bem vindas, e acho que quando fecharmos uma redação boa, podemos publicar nos principais canais. Deve, claro, já ter algum BOM material por aí que torna este completamente dispensável, mas não pesquisei ainda, e este aqui é um apanhado de idéias loucas e ainda sem organização que eu tive durante um surto na febre da dor de garganta que minha amada e idolatrada esposa passou para mim. ;-) *Como escrever artigos técnicos v0.0.1* *Introdução/Resumo:* Encontramos hoje uma infinidade de artigos técnicos na internet, tão vasta quanto as necessidades de cada ser humano que acessa a rede. Porém, tais artigos pecam em vários sentidos. Não pecam pelo compartilhamento do conhecimento, esta na verdade é sua maior virtude. Mas pecam ao não definirem bem os limites da validade daquele conhecimento. O maior problema de todos, na verdade, é a ausência da constante revisão do autor sobre a validade daquele conhecimento, e da sua substituição por conhecimento novo. Muitas vezes encontramos artigos que citam recursos (features) que não estão mais disponíveis para as versões recentes de um software/linguagem de programação, o que deixa o leitor perplexo pelo fato do artigo "não funcionar", ou, em casos mais extremos, travar completamente o computador/servidor levando a decisões drásticas como a reinstalação de todo o OS. Este texto visa justamente definir linhas guias sobre como escrever artigos técnicos específicos de TI (Tecnologia da Informação) a fim de auxiliar não apenas os autores, mas os leitores também, a identificar onde pode estar uma falha em um artigo, e contribuir para sua correção e atualização constantes. Os artigos técnicos de TI diferenciam-se substancialmente (mas não completamente) de artigos acadêmicos, visto que a grande maioria tem por "bibliografia" apenas as experiências empíricas do autor. Citar o manual de um software como referência, não ajuda, e muitas vezes irrita o leitor - RTFM - fazendo com que a leitura senha abandonada. O conhecimento é um apanhado de tantos outros artigos que o autor não consegue indicar uma bibliografia exata. Também não é raro o fato do autor não ser um escritor e não ter o conhecimento necessário para organizar e compartilhar conhecimento - muitos são auto-didatas, mas as bases da comunicação efetiva não são facilmente assimiladas - parecendo-lhe que o artigo escrito explica tudo, quando na verdade há diversas lacunas a serem preenchidas. Mais do que isso, no geral, autores de TI (a menos que acadêmicos ou, ainda, pessoas com foco maior em gestão de TI do que em técnicas de TI) raramente voltam aos seus antigos textos - a menos que o mesmo problema se apresente novamente - deixando-os eternamente publicados sem revisão ou ainda indicação de que o conhecimento ali publicado tornou-se obsoleto e foi substituído por novo conhecimento em outro artigo. *Objetivo deste artigo:* Definir orientações que servem para auxiliar autores e leitores de artigos técnicos a identificarem falhas e possíveis melhorias para textos técnicos, além de sugerir o cultivo de certos hábitos a fim de auxiliar todas as comunidades a manterem de maneira mais eficaz o conhecimento de determinada área da TI. *Aplicável a:* Sistema operacional: TODOS Software: TODOS Público: Todos os níveis *Pré-requisitos:* - Mente aberta e pronta a descartar o que você acha que já sabe - Ter muita vontade de escrever artigos e dar manutenção em artigos antigos *Estrutura dissertativa básica para um bom artigo técnico* Este artigo, antes de mais nada, é uma experiência sujeita às próprias idéias aqui transcritas a fim de testar e comprovar a eficácia das idéias subjetivas do autor sobre como escrever artigos. Algumas das idéias aqui anotadas poderão parecer "exageradas" e "desnecessárias" à princípio, porém, com o passar do tempo, e de acordo com o volume de conhecimento gerado e mantido por você, leitor, talvez elas passem a fazer mais sentido. A primeira coisa a definir é aquilo que seu professor de português/redação já insistia a muito durante sua formação básica e média: é preciso, antes de mais nada, estruturar as idéias! A estrutura mais básica que existe é: *Título/Subtítulo* - resumo da idéia *Introdução* - porque o artigo é necessário *Conteúdo* - o conteúdo em si *Conclusão* - o que você espera com este artigo Acrescentemos mais alguns, essenciais para um bom artigo de TI? *Título/Subtítulo* - resumo da idéia *com versionamento* *Introdução* - porque o artigo é necessário *Objetivo - o que se espera com o artigo* *Aplicável a - plataformas e softwares ao qual o artigo é aplicável com a versão dos utilizados* *Pré-requisitos - links para artigos que seriam aconselháveis ao leitor acessar antes de prosseguir* *Tornou-se obsoleto por: links para artigos que atualizam o conhecimento aqui disponibilizado para novas versões* Conteúdo - o conteúdo em si Conclusão - o que você espera com este artigo Como vê, não é tão complicado, são apenas 4 itens a mais, sendo que o primeiro, normalmente é encontrado em textos acadêmicos, e os três seguintes criam o necessário para dar um "prazo" (versão) para o qual o conhecimento é válido, mostrar o que a pessoa precisaria saber antes de ler o restante do artigo, além de levar ao conhecimento que substitui este. Este último é um recurso muito fácil de ser localizado nas RFCs e também nos padrões ISO, ou seja, não é uma idéia "nova" nem "inventada" por mim, mas simplesmente algo que não se observa nos artigos que são encontrados na internet atualmente. Aliás, certos sites deveriam aderir a fazer isso permitindo não apenas que o autor indicasse novos conhecimentos, mas que os leitores indicassem os artigos que tornaram o conteúdo obsoleto. Isso com certeza já seria um plus. Voltando ao assunto do nosso artigo... (obs: a maior parte do que eu queria dizer já foi dito até este ponto, você pode dispensar o resto da leitura já que será uma aula básica de redação). *Título/Subtítulo* Como organizar as idéias? É muito mais simples do que parece: defina um assunto. Normalmente, seu assunto acabará virando o título de seu artigo. Não se assuste: você está escrevendo um artigo técnico! Como todo autor você tem direito a Título (resumão) e subtítulo (uma frase mais elaborada para definir a idéia), como se fosse um jornalista escrevendo uma matéria. Não precisa subtítulo? Melhor ainda, isso mostra que sua idéia é conscisa e direta! Mas se precisar, use, não desperdice esse recurso. Ele também é muito útil para dividir o artigo em "partes" Você pode (na verdade, se quiser realmente ter sucesso, deve) começar por definir o título. Se você conseguir resumir sua idéia para o artigo a uma frase, então já está muito bem encaminhado. Se não, pode ser que sua idéia precise ser quebrada em diversos artigos. É muito comum as pessoas começarem um artigo sobre configuração de firewall querendo falar sobre a instalação do OS do firewall. Se seu artigo é sobre firewall, então ele não deve cobrir a instalação do OS! Mas, se você está com os dedos "coçando" para digitar e explicar sobre a instalação de determinado OS (OpenBSD, por exemplo, é um capítulo à parte, pode exigir recompilação de kernel, instalação específica, etc), prepare-se: você tem 2 ou mais artigos em mãos, sendo que um citará o outro como "pré-requisito". Então, se seu título não contiver apenas 1 idéia, pare, divida as idéias, e escreva tantos artigos quantas idéias você tiver. Bem vindo ao mundo da internet, onde o hiperlink cuidará da vinculação dos conhecimentos para você. Isso criará artigos mais curtos, e dispensará quem já conhece um pouco o assunto de ficar lendo o que já sabe. Obviamente você sabe como é chato ter que filtrar um bom artigo ignorando a parte que você já sabe. Definido o título, e, definida a idéia a uma só, vamos começar a pensar o subtítulo. Como dito antes, não é obrigatório, mas, recomendável, que se crie um subtítulo. O objetivo é descrever um pouco melhor sobre o que trata o artigo, sem obrigar a pessoa a ler uma introdução e um objetivo. Existem artigos meramente teóricos e existem artigos práticos, por exemplo, que cabem no mesmo título. Vamos ver 2 exemplos? Título: Firewalls Linux Subtítulo 1: Como elaborar regras eficazes de segurança para sua intranet Subtítulo 2: Como configurar o iptables com Debian Deu para ver a diferença? Ambos os artigos tratam de firewalls no Linux, mas o primeiro tenta te orientar de forma teórica (na verdade, ele não deveria citar o Linux no título, pois a teoria poderia servir para qualquer artigo, mas, eu precisava de um exemplo!), enquanto o segundo já mostra a configuração prática mesmo, como inserir regras e tal. Percebeu também que ambos cabem no mesmo título, mas são artigos diferentes? ;-) Uma vez definido o título e subtítulo, os quais, preciso dizer, pois sempre tem quem segue muito ao pé da letra, não foram talhados na pedra e podem ser alterados caso necessário, vamos pensar na introdução. *Introdução* O que é a introdução? A introdução é o motivo que te levou a escrever o artigo. Note nossa introdução. Eu percebi que há uma falha na forma como os artigos são escritos, e resolvi aproveitar a meu diploma mofado e sem uso de "Comunicação Social - Jornalismo" para tentar criar uma leva de artigos melhores. Conheço muuuuitos, mas muitos mesmo, técnicos que detém um conhecimento muito aquém do que permite minha vã consciência. E sei que muuuuitos, mas muitos mesmo, não sabem colocar esse conhecimento no papel. Isso é um fato! Se todos conseguissem comunicar-se bem na forma escrita, e se todos conseguissem interpretar bem na mesma forma, não teríamos sistemas onde o cliente pede uma coisa, o analista documenta outra, e o desenvolvedor entende outra. Enfim, vamos ser sinceros conosco: todos somos falhos quando a questão é nos comunicar. Eu mesmo devo ter errado horrores neste texto (me corrijam, por favor!!!) Enfim, este foi o motivo que me levou, mas mais importante que este, foi a necessidade que percebi de uma estrutura básica onde coloquemos "data de validade" em nossas informações e mantenhamos o leitor em direção à informação atualizada sempre. Então, qual foi seu motivo? Qual a sua história? O que você passou que te levou a escrever esse artigo? Vale tudo neste ponto, até mesmo dizer: "eu não encontrei informação para meu problema" porque essa é a coisa mais comum do mundo! Veja a quantidade de perguntas em fóruns e listas não respondidos e pronto. Isso acontece! E se alguém te mostrar um outro artigo no futuro, ótimo, mas na época, não tinha, ou até tinha e você não achou, e pronto! Conte sua história. Vai ficar impressionado com a quantidade de simpatizantes na mesma situação que irá encontrar. Essa é sua introdução. *Objetivo* E seu objetivo? Bom, seu objetivo pode ser algo simples como "Estou registrando para futuras referências pessoais" até algo como "Quero ajudar a comunidade a ser melhor". Simples, não? Qual o objetivo do seu artigo? Documentar apenas? Ok. Compartilhar? Ok. O importante é saber que você não escreveu algo com o objetivo de "tentar deixar este fim de semana melhor e ver se minha teoria sobre a velocidade da luz e redes mais rápidas estava correta". Tenha um objetivo! Isso torna seu esforço algo valoroso, mesmo que você não saiba. *Aplicável a* Este título é auto-explicável, mas acredite: pouca gente faz! Seu artigo técnico é aplicável a algo, que pode ser tão genérico quanto TODOS (caso deste artigo) quanto a um OS, Software e versões específicas. É simples, apenas enumere o que você usou. Acredite, é tão simples quanto isso. Mas enumerar aqui é muito diferente de citar no meio do artigo. Veja, se eu sei que é para Debian com Iptables e eu estou buscando OpenBSD com pf, eu simplesmente paro de ler aqui mesmo! Não gasto um tempão atrás de um título mal escrito (Configurando Firewalls) que é específico para Debian com Iptables mas não tinha subtítulo, nem ao que era aplicável. Acredite: isso salva almas! Além de (se tornar-se um padrão) ser mais fácil de achar em máquinas de busca. *Pré-requisitos* ** Muitas vezes um conhecimento requer conhecimento de outro. Tem muita gente que quer montar um firewall OpenBSD porque ouviu que era melhor para bordas, mas nem sabe instalar o OpenBSD. Aliás, nunca mexeu em um BSD, só usou Ubuntu e acha que já saca tudo de Unix (Ubuntu r0x, mas é porta de entrada de muito newbie, como PHP é para muito newbie dev). acredite: a pessoa gostaria de ter algumas indicações sobre como instalar e usar. Não é à toa que isto está aqui. Artigos acadêmicos não tem este tipo de informação. Eis outra diferenciação. ** *Tornou-se obsoleto por:* ** É aqui que entra a importância em reler o que se escreve. Muitas vezes alguém pode querer informação sobre as versões que o artigo cobre. Mas nada é mais frustrante que gastar horas compilando e configurando para descobrir que aquilo não se aplica mais desde 2006. É froids! Quer referências de sites que fazem isso? Que tal estes? http://www.rfc-editor.org/cgi-bin/rfcsearch.pl - pesquise qualquer coisa (mail é uma sugestão), e note a coluna "More Info". http://www.iso.org/iso/catalogue_detail?csnumber=39612 - note a informação no final da página "Revision' *Conteúdo* Se você não souber o conteúdo, quem sou eu para te explicar? *Conclusão* Toda idéia tem uma conclusão. Qual foi a sua? Pode ser qualquer coisa como "Funcionou para mim, espero que funcione para você. Se não funcionar, diga-me onde corrigir" ou ainda "Acredito que algum dia alguém fará um script que resolva de forma mais automatizada" ou, melhor ainda, "Estou desenvolvendo uma ferramenta para automatizar tudo isto. Ela está em http://www.sf.net/projects/só1exemplo e com certeza seria bom ter sua contribuição. *Conclusão (deste artigo)* ** ** Este artigo está longe de completo, e é só um esboço do que está por vir. Por favor, contribua, nem que seja lendo e criticando apenas, mas se puder dar sugestões, será melhor ainda. Um abc -- * Pablo Santiago Sánchez* ZCE ZEND006757 [email protected] (61) 9975-0883 http://www.sansis.com.br *"Pluralitas non est ponenda sine necessitate"* -- * Pablo Santiago Sánchez* ZCE ZEND006757 [email protected] (61) 9975-0883 http://www.sansis.com.br *"Pluralitas non est ponenda sine necessitate"*
_______________________________________________ pgbr-geral mailing list [email protected] https://listas.postgresql.org.br/cgi-bin/mailman/listinfo/pgbr-geral
