Um dos pontos positivos de uma Wiki é a agilidade com que se constrói colaborativamente o conhecimento dentro dela. Porém isso tem um preço: rapidamente ela pode ficar bagunçada e com estruturas incoerentes entre si. Por isso, é importante definir algumas diretrizes básicas de como essa colaboração deve ser feita, para que possamos preservar uma estrutura comum.

Esse é um trabalho contínuo, que vai evoluindo conforme a Wiki toma forma, e de tempos em tempos pode precisar ser atualizado.

Convenções de edição dizem respeito ao modo como o texto deve ser formatado. Consulte a sintaxe do DokuWiki para saber como o texto pode ser formatado.

Quando fizer referência a esta wiki especificamente (isto é, Slackjeff Wiki), inicie por letra maiúscula:

Há várias maneiras de contribuir para a Wiki.

Por outro lado, quando quiser se referir a qualquer wiki (isto é, o conceito de wiki como sistema de gerenciamento de conteúdo), use itálico e inicie em letra minúscula:

Uma wiki é uma forma prática de edição colaborativa.

Ao apresentar novos conceitos ou termos chave para um determinado texto, eles devem ser destacados em negrito (na primeira ocorrência do termo dentro da página).

Valores de primeira classe podem ser armazenados em variáveis e passados como argumentos em funções.

Entretanto, se esses termos já estiverem descritos em um glossário, eles devem ser grifados com itálico, e possui um hyperlink para a página do glossário, especificando a letra do termo referido. Logo após o termo deve ser usado um emoticon de interrogação. Essa forma de destaque também só deve ser feita na primeira ocorrência do termo dentro da página.

O paginador more é um programa padronizado pelo POSIX.

Nomes de programas, drivers, serviços, arquivos de configuração e diretórios de sistema devem sempre aparecer sublinhados.

O interpretador sh tipicamente é uma referência a alguma implementação aderente ao padrão POSIX (como dash, por exemplo).

Uma exceção a essa regra é quando o programa, driver, arquivo, etc é mencionado pela primeira vez no texto, e ele é o assunto principal sendo abordado. Nesse caso deverá ser destacado em negrito.

O editor ed é o editor de texto original do UNIX.

Quando parâmetros de linha de comando forem mencionados, eles também devem ser destacados em negrito. A mesma regra vale para subcomandos de programas de linha de comando .

Ao usar o parâmetro -1, a lista apresentada por ls será forçada a usar uma única coluna.

Embora não seja parte do padrão, quase todas as implementações do editor ed possuem o comando z, que pode ser útil para visualizar o arquivo.

Por vezes, usamos termos estrangeiros (geralmente em inglês), que não possuem uma tradução ou não faria sentido traduzir (ou ainda, que poderia soar muito pedante a tradução). Esses termos devem ser destacados em itálico.

Certifique-se de haja espaço suficiente para o backup agendado.

Trechos de especificações e documentos externos devem aparecer na forma de citação (ou seja, dentro de um bloco de citação, e em itálico). Aspas externas não são requeridas.

The term “user agent” refers to any of the various client programs that initiate a request.

Toda página deve possuir um título de nível 1. O uso de títulos em níveis inferiores depende da página sendo editada. O uso de títulos para agrupar partes relacionadas do conteúdo é encorajado, enquanto isso servir para facilitar o entendimento do conteúdo sem prejudicar a legibilidade.

Como guia de organização, cada tópico principal (vide descrição de tópicos principais) pode possuir suas próprias convenções de titulação e organização do conteúdo.

Essa instância do DokuWiki possui um plugin de notas (Note Plugin). As notas devem ser usadas para destacar informações relevantes para o assunto sendo abordado. Existem quatro tipos diferentes de notas, e elas possuem conotações diferentes.

A nota genérica provavelmente será a mais comum. Qualquer assunto que mereça destaque pode ser incluído nesse tipo de nota, geralmente sem uma conotação de recomendação ou contra-indicação. O objetivo é dar mais visibilidade a algum aspecto do texto que possa ter passado despercebido.

A nota de dicas pode ser usada para reforçar alguma capacidade ou possibilidade que o leitor não percebeu que teria, algo que ele pode ter interesse em fazer e não havia percebido que podia, ou que pode ser benéfico em alguns casos mais específicos.

A nota importante serve para alertas que não devem ser ignorados pelo usuário, em geral com recomendações de algo que ele deve fazer ou ter em consideração ao executar alguma ação.

Por fim, a nota de alerta tem uma conotação de contra-indicação ou de cuidado, isto é, alertando para algo que pode causar problemas ou que deve ser evitado.

O uso de um ícone e cor específica já adiciona alguma conotação à mensagem. Mas você pode querer ir além e definir um pseudotítulo (pseudo nesse caso por não se tratar de um título formal do documento), que ajude a explicar por que a mensagem está dentro de uma nota.

Por exemplo:

Alguns títulos que podem fazer sentido (por tipo de nota):

• Notas genéricas: Você sabia?
• Notas de dica: Fique por dentro!
• Notas importantes: Atenção!
• Notas de alerta: Cuidado!

De modo geral, se a conotação já for bastante óbvia (especialmente se for uma mensagem mais curta), o uso do título pode ser dispensado.

A principal matéria prima de uma Wiki é o texto. Mas em alguns casos particulares, uma imagem “vale mais que mil palavras” e pode fazer sentido incluir, para contribuir com a transmissão de uma mensagem. O que não deve ser feito é incluir imagens ao acaso, apenas por incluir ou sem uma contribuição significativa para o conteúdo sendo abordado, pois nesse caso seria apenas poluição visual.

É importante também considerar o fato de que imagens ocupam mais espaço que texto e são menos compactáveis. A fim de otimizar o uso de recursos da Wiki, as imagens devem, além de contribuir significativamente para o conteúdo, possuir um formato com boa compressão e um tamanho máximo.

Portanto, o formato JPEG deverá ser utilizado para as imagens incluídas aqui, já que é um formato com boa compressão, e não deve extrapolar uma dimensão de 800×600 pixels. Para os (potencialmente) raros casos em que a qualidade da imagem precise ser preservada ao redimensionar, use o formato SVG.

Por motivos de acessibilidade, é importante que toda imagem adicionada possua uma legenda.

A sintaxe do DokuWiki admite o uso de emoticons. Para evitar a perda de significado, nenhum emoticon deve ser usado, a não ser nos casos a seguir:

O sinal de interrogação deve ser usado em referência a termos de glossário (para exemplo, vide tipografia).

O indicativo de correções deve ser usado em trechos onde se sabe que algum texto deve ser melhor elaborado, detalhando o motivo. Por exemplo:

Detalhar quais predicados são aceitos nesse tipo de consulta.

…

Toda página de glossário deve possuir uma tabela indicativa das letras utilizadas. A tabela deve ser organizada em uma matriz de 2 x 13, isto é, duas linhas com 13 colunas, em que cada célula é uma das letras do alfabeto (representadas sempre em caixa alta). Apenas as letras utilizadas no glossário devem possuir um hyperlink para a seção correspondente. Todas as letras deverão aparecer centralizadas dentro da célula.

A tabela deverá possuir um cabeçalho intitulado “Buscar por letra”, para deixar explícita a finalidade dessa tabela.

Por exemplo, para um glossário que possua termos para as letras D, H, I, N, R e Z, deverá ficar assim:

Toda vez que um novo termo for adicionado e esse termo iniciar por uma letra que ainda não estava sendo usada no glossário, a tabela deverá ser atualizada, para incluir o hyperlink correspondente.

Convenções de redação dizem respeito ao modo como os tópicos devem ser organizados, e como os textos devem ser construídos.

A página inicial da Wiki possui uma lista de tópicos principais. Essa lista não deve ser alterada sem uma discussão prévia, por serem tópicos mais genéricos, elaborados a partir de páginas que já existiam, capturando a essência dos assuntos.

Caso se perceba que um novo tópico principal é realmente necessário, ou seja, que os já existentes não cobrem algum assunto de interesse para a Wiki, então uma nova discussão deverá ser iniciada no fórum.

Cada um dos tópicos principais possui sua própria página inicial, a qual deve iniciar por uma explicação resumida do que aquele tópico abrange. Os títulos dessas páginas devem ser o nome por extenso do tópico (por exemplo, “Utilitários”), que deve ser seguido por uma linha destacando o nome de contexto daquele tópico (para mais informações, vide a seção de convenções de contexto, mais adiante).

(Contexto: utils)

Além disso, a página deverá possuir uma primeira seção intitulada Introdução, para explicar a abrangência daquele assunto. Essa seção deverá apresentar um hyperlink para um glossários de termos daquele tópico (se houver um), e para as convenções de organização do conteúdo daquele assunto (novamente, se houver).

Hyperlinks para outras páginas poderão ser organizados dentro dessa página inicial do tópico, incluindo páginas de outros tópicos.

Tópicos principais podem possuir termos técnicos de uso recorrente que podem levantar dúvidas sobre seu significado. No lugar de explicar esses termos para cada uma das páginas onde forem utilizados, é interessante que haja uma referência que centraliza a explicação do termo.

Não é desejável que haja apenas um único glossário para toda a Wiki pois os termos podem assumir significados diferentes dentro de contextos diferentes. Então, para cada um dos tópicos principais da Wiki deve haver um glossário (podendo não haver nenhum, se não houver termos a serem explicados para aquele assunto específico).

Cada glossário deve possuir sua própria página (ou seja, o conteúdo do glossário não deve ser embutido em páginas abordando algum outro assunto, nem serem adicionados diretamente à página inicial de algum tópico principal).

Uma página de glossário deve organizar os termos por ordem alfabética, sendo cada uma das seções da página representada pela letra do alfabeto, assim podem ser referenciadas para a busca de um termo. A página deve iniciar com uma explicação daquele contexto (ou seja, de que termos aquele glossário trata), e uma tabela com referências para todas as letras utilizadas, seguindo a proposta de tabela de glossário, apresentada nas convenções de edição (seção de tabelas).

Em glossários os termos devem ser explicados de forma sucinta, se estendendo no máximo por um parágrafo. Se uma explicação mais detalhada for necessária, então é interessante que haja uma página (ou trecho de alguma página relacionada) dedicada ao assunto, e no glossário apenas uma explicação mais resumida, que apresenta um hyperlink para a explicação completa.

Em alguns casos, pode-se perceber que algum assunto é importante para a página sendo construída, mas o texto ainda não foi elaborado (algo que será deixado para depois). Nesses casos, o indicado é criar a seção/subseção vazia, isto é, no lugar do texto colocar apenas reticências (…) para indicar que aquele trecho ainda está pendente.

…

Sempre que possível, faça uma revisão ortográfica e gramatical dos textos que incluir. A correção é uma das marcas de qualidade de uma Wiki, não apenas por transmitir a mensagem com mais precisão, mas também por evitar que erros sejam reproduzidos depois por incautos (isto é, evita que alguém tome por certo algo que está errado, apenas porque leu na Wiki).

Um texto enxuto ajuda o leitor a manter o foco. Evite a repetição sempre que possível. Em alguns casos mais específicos, a redundância pode ter uma função de reforçar algum ponto mais importante, mas em geral isso deve ser feito em pontos distantes de um texto. Repetir falas em um mesmo parágrafo ou parágrafos próximos é contraindicado.

Exemplo de texto prolixo (não conciso):

Ao operar na frequência máxima o processador tende a consumir mais energia e esquentar, e nem sempre isso será necessário, então não deve operar no máximo, pois assim ele tende a desperdiçar energia e aquecer o computador.

Exemplo de texto conciso:

Não é ideal que um processador opere na frequência máxima, pois ocasiona maior consumo de energia e aquecimento, geralmente sem benefícios perceptíveis.

Se mesmo mantendo a informação concisa, perceber que os parágrafos estão ficando grandes, procure dividí-los, de modo que cada parágrafo trate de uma parcela da informação.

Por exemplo, o seguinte parágrafo possui informações demais:

O código-fonte C pode possuir embutido dentro de si uma ou mais diretivas de pré-processamento. Essas diretivas não são parte da linguagem C, propriamente. Elas são parte de uma linguagem complementar, de macroprocessamento, que deverá gerar código C após uma etapa inicial do processo de compilação, como um todo. Diretivas como #include e #define, por exemplo, são muito comuns e tem (respectivamente) como função reutilizar código definido em outro arquivo, e para diretamente definir valores de substituição. Ou seja, diretivas ajudam a deixar dinâmico o código-fonte C a ser compilado.

Ele poderia ser dividido como a seguir:

O código-fonte C pode possuir embutido dentro de si uma ou mais diretivas de pré-processamento. Essas diretivas não são parte da linguagem C, propriamente. Elas são parte de uma linguagem complementar, de macroprocessamento, que deverá gerar código C após uma etapa inicial do processo de compilação, como um todo.

Diretivas como #include e #define, por exemplo, são muito comuns e tem (respectivamente) como função reutilizar código definido em outro arquivo, e para diretamente definir valores de substituição. Ou seja, diretivas ajudam a deixar dinâmico o código-fonte C a ser compilado.

Essa regra também vale para parágrafos dentro de notas (vide Notas, nas convenções de edição). Tipicamente, essas mensagens serão curtas o bastante para que um parágrafo único seja o ideal. Mas se perceber que a legibilidade ficou ruim devido ao tamanho do parágrafo, é preferível dividir.

Como o espaço dentro de notas é mais curto, você pode definir parágrafos um pouco menores do que definiria fora de uma nota.

Existem termos estrangeiros que podem não fazer sentido traduzidos. Nestes casos, o ideal é usar o termo estrangeiro mesmo (devidamente grifado, como indicado nas convenções de edição). É o caso de termos como driver, lint, shell e prompt, só para citar alguns.

Ao iniciar um laço iterativo, o prompt primário será substituído pelo secundário.

Existem também termos que até podem ter alguma tradução, mas que seja pouco usual e possa soar pedante. Por exemplo, o termo becape pode ser usado no lugar de backup, mas seu uso é pouco comum. O mesmo ocorre com leiaute no lugar de layout. Nesses casos, fica a critério do redator qual termo utilizar, mas no caso de preferir o termo estrangeiro, deverá ser grifado.

Crie uma partição separada para armazenar o becape.

Não se esqueça de agendar as rotinas de backup.

Por fim, existem casos em que nos apropriamos de uma palavra estrangeira como se fizesse parte da língua portuguesa. Alguns casos desse tipo são muito comuns e podem ser usados, como deletar (apagar). Mas no geral, devem ser evitados, se houver algum termo equivalente em português que transmitirá a mensagem com mais acurácia.

Exemplo evitável:

Depois de ajustar as configurações, dê um refresh na página.

Sugestão de alternativa:

Depois de ajustar as configurações, atualize a página.

No DokuWiki, o conteúdo das páginas é versionado conforme é modificado. Convenções de versionamento dizem respeito ao modo como essas versões devem se estabelecer.

Ao alterar uma página, é possível marcar a opção “Alterações mínimas”. O que isso significa?

Existem dois tipos de modificação que podem ser aplicadas em um texto: alterações normais, isto é, alterações que possuem relevância ou mudança de significado, e alterações mínimas, que são reservadas para edições que não alteram o significado de modo perceptível.

Determinar o que é relevante ou não é um pouco subjetivo, portanto as convenções apresentadas aqui servem para dar um pouco mais de objetividade a esse critério.

Alterações mínimas devem ser aplicadas quando:

• Apenas correções ortográficas, gramaticais ou tipográficas tiverem sido aplicadas ao texto;
• Uma nova seção ou subseção tiver sido criada, mas ainda sem conteúdo;
• Substituição de um termo por algum sinônimo que se encaixe melhor no texto.

Ao aplicar alterações em uma página, uma descrição para o motivo da alteração deve ser preenchido no “Resumo da edição”. Como diz o nome, o ideal é que seja uma descrição resumida, o que não quer dizer que possa ser evasiva, insignificante ou meramente protocolar. Deve ser uma descrição que de fato explique o porquê da alteração.

Exemplos de boas descrições:

Detalhamento de comando join

Consequências de interrupção não estavam evidentes

Exemplos de más descrições:

Configuração

Novo comando

Quando a alteração (seja ela normal ou mínima) for aplicada a uma seção específica do documento, o Dokuwiki automaticamente sugerirá a inclusão da seção entre colchetes no início do resumo. Por exemplo:

[Descrição das versões] Sugestões de descrição (normal ou mínima)

Para alterações mínimas, basta descrever o tipo de correção aplicada (ou os tipos), ou apenas descrever que uma seção vazia foi criada. Exemplos:

Correção tipográfica

Correções ortográfica e gramatical

No caso de seções vazias sendo criadas, a seção em questão deverá ser destacada. Por exemplo:

[Padronização] Seção criada (vazio)

Convenções de contexto dizem respeito à organização das páginas em termos de aplicação de namespaces, um recurso do Dokuwiki que permite definir as páginas conforme algum contexto específico, e aplicar algumas regras diferentes (como barra lateral, por exemplo) para cada contexto.

Para cada um dos tópicos principais dessa wiki, deve ser utilizado um mesmo contexto. Páginas de contextos diferentes podem referenciar umas às outras, quando isso fizer sentido.

Cada uma das páginas iniciais de tópicos principais deve seguir a convenção de nome namespace:start (onde namespace nesse caso será o nome usado para a namespace daquele tópico). Portanto, a página prog:start servirá como página inicial para o tópico de programação, enquanto seg:start servirá como página inicial para o tópico de segurança.

Páginas de contextos diferentes podem ter o mesmo nome, se isso fizer sentido. É o caso não apenas das páginas iniciais (isto é, start), mas também de páginas de glossários, que seguirão a convenção namespace:glossario. Logo, podemos também ter a página prog:glossario para um glossário de termos da programação, e seg:glossario para um glossário de termos usados em segurança da informação.

Com exceção da página inicial e algumas páginas de tópicos administrativos, todas as páginas criadas devem possuir um contexto. Em alguns casos, decidir qual é o contexto pertinente pode ser um pouco difícil pois alguns assuntos podem se encaixar em mais de um contexto. Nesses casos, deve-se escolher o que tiver a relação mais forte com o assunto. E vale lembrar, nada impede que a página de um contexto faça referência a uma página de outro contexto.

…