This is a copy of a document written by Colin Walters. The document has not been updated since Jun 30, 2007 and is likely obsolete. See the internet archive.
Translated by Gustavo Franco <gustavo@digirati.com.br>.
(English)
As descrições de pacotes debian são basicamente uma forma de anúncio, contudo informativo e útil.Eles são um caminho para atrair usuários para o seu pacote, e passar detalhes importantes sobre o mesmo.No anúncio, a idéia chave é conheça seu público.Este é o princípio que você deve utilizar quando estiver escrevendo descrições de pacotes Debian.Por exemplo, pense sobre que tipo de pessoas utilizam seu pacote(programadores, biologos, músicos, geneticistas), o nível de conhecimento sobre computadores que eles têm, e o tipo de palavras chave que eles estão procurando.
Historicamente, a Debian tem um público muito técnico.Isto se reflete em diversas coisas no projeto, mas as descrições dos pacotes é um aspecto óbvio.Como uma consequência, nossas descrições de pacotes são na maioria dos casos voltadas a usuários técnicos, que conhecem GNU/Linux muito bem.Elas estão cheias de expressões técnicas como "GTK+", "X", "binaries", e "GUI".Elas presumem um alto nível de entendimento de computação.
Em alguns casos, isto não é uma coisa ruim.Dê uma olhada no pacote glade como exemplo.Sua descrição curta atualmente é "GTK+ User Interface Builder", e a longa contém "Glade is a RAD tool...".O público do Glade é definitivamente composto por pessoas que sabem o que GTK+ e RAD são; programadores, que geralmente tem um alto nível de conhecimento técnico.Para eles, expandir RAD em Rapid Application Development não é necessário, porém isto não é uma idéia ruim em todos os casos.Eles provavelmente saberão o que GTK+ é.
Em contraste, dê uma olhada no pacote rhythmbox. Neste caso, o público atingido é muito amplo; muitos que querem ouvir música em seus computadores.Um exemplo de descrição ruim pode ser: "GTK+/GNOME music player like xmms and iTunes".Isto pode ajudar a imaginar um amigo ou alguem que não seja muito técnico olhando para a descrição do pacote.Para ele, "xmms", "GTK+", e "iTunes" são termos aparentemente completamente sem sentido. É bem possível que GNOME seja também, mas nós vamos abordar este assunto em um minuto.Um usuário novato lendo isto deve ignorar o pacote antes mesmo de ler a descrição completa, porque ele parece muito desafiador.Se você é um usuário experiente de computadores, pode achar que isso parece exagero, mas isto realmente acontece.
Então como nos podemos atingir melhor estes usuários? A resposta é reescrever a descrição para que ela faça sentido para a maioria dos usuários, mantendo um mínimo de termos técnicos para que ela seja útil para usuários avançados ainda.Aqui está a descrição atual: "music player for GNOME".Nesta, "music player" aparece primeiro.Que deve satisfazer todos os novatos.Agora os usuários intermediários e avançados podem ver "GNOME" no final, e saber que isso significa que o programa estará integrado com seu ambiente de trabalho.Os usuários novatos podem não saber o que significa este termo, mas eles podem aprender a ignorar isso.(eles vão aprender isto, como a maioria dos usuários de computadores tem uma vaga idéia do que o "Windows" é).
Até aqui nós discutimos a descrição curta principalmente; todos estes princípios se aplicam para o resto da descrição.Em todos os casos, a descrição longa deve ser escrita tendo em mente que o usuário já leu a descrição curta, e estava interessado o bastante para ler o resto da descrição.O que faz disto um bom lugar para explicar que opções o programa tem, como ele é diferente das alternativas, etc.Fazendo isto, você deve gradualmente detalhar mais e mais, assim como qualquer outro bom anúncio.De novo, geralmente deixe de lado termos técnicos na primeira sentença do primeiro parágrafo, mas sinta-se a vontade para usa-los depois.
Novamente, acima somente foi abordado as linhas gerais; o princípio de conheça seu público deve ser o mais importante guide.Por exemplo, o pacote fastdnaml é bem óbvio que tem como alvo biólogos.Sua descrição curta contém termos como "phylogenetic trees" que são totalmente sem sentido para mim, mas que para um biólogo eles provavelmente fazem algum sentido. Neste pacote, é perfeitamente aceitável que a sua descrição utilize esses termos de forma proeminente.
Uma outra nota é que enquanto nós fizemos a analogia de que a descrição de um pacote deve ter a forma de um anúncio, eles também devem ser o mais informativo possível.Isto que dizer que dizer coisas como "This package is the best!!!" não é realmente informativo.É duvidoso que isto seja uma forma efetiva de anúncio.Se outro pacote suportar uma opção que o seu não tiver ainda, não parece uma má ideia mencionar isso na sua descrição. Lembre, o objetivo final e ajudar o usuário.
Dê uma olhada na seguinte lista de verificação, e tenha certeza que sua descrição satisfaz o critério.1:
Sua descrição segue as linhas gerais do Debian Policy?
O que isso faz(em termos não técnicos)?
Você precisa disso? (Dê uma olhada na última sentença das descrições do Configure.help no Linux -- elas são realmente úteis se você não quer entender a coisa porque você não precisa disso, mas tem que fazer uma escolha agora)
Quais são as opções melhores e as deficiências se comparado a outros pacotes (se você precisa de X, use Y ao inves deste)?
Este pacote está relacionado com algum outro pacote de alguma forma que não é interpretada pelo gerenciador de pacotes (este é o cliente para o servidor foo)?
Agora, deixe me colocar todas estas linhas gerais juntas em um exemplo bem genérico.Você deve utilizar a criatividade aqui; obviamente o que esta abaixo não esta próximo de ser uma boa e real descrição.Isto precisa ser um pouco mais robusto.
Package: foo Description: <executa uma função, realiza alguma tarefa> <para GNOME/KDE/WindowMaker/GNU/Linux> foo é um <programa> desenhado para ajudar sua <tarefa>. <detalhes mais simples sobre a tarefa>. Escrito para o <ambiente>, ele suporta <opção1> e <opção2>. . Outras opções são <opção3> e <opção4>. <detalhes mais avançados para usuários técnicos>.Veja o <outro pacote> para mais detalhes. . <Este pacote esta atualmente em estágio alpha/beta...> . <Você pode encontrar maiores informações sobre foo em http://www.foo.org.>
Existem uns poucos problemas de estilo que ainda não foram resolvidos no projeto hoje; alguns deles(especialmente os da descrição curta) tem sido amplamente discutidos, sem um consenso aparente.
O número de espaços após um parágrafo - um ou dois? Parece que de forma geral os americanos usam dois espaços e os europeus utilizam um.Em todo caso, o consenso a que se chegou na debian-devel é que dois espaços devem ser utilizados para simular espaço extra depois do final das sentenças em fontes de largura fixa.
Se deve ou não a descrição curta ser encerrada com um ponto (.); veja o bug #139957.
Se deve ou não o início da descrição curta ser em maiuscula.
1 Agradecimentos a Simon Richter <sjr@debian.org> pela maior parte da lista de verificação.