Diferenças

Aqui você vê as diferenças entre duas revisões dessa página.

--- wiki:convencoes [2024/12/10 05:42] – [Concisão] tamanho menor dentro da nota hrcerq
+++ wiki:convencoes [2024/12/15 23:47] (atual) – desativada em favor de admin:wiki:convencoes hrcerq
@@ Linha 1: / Linha 1: @@
-====== Convenções da Wiki ======
-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 =====
-Convenções de edição dizem respeito ao modo como o texto deve ser formatado. Consulte a [[wiki:syntax|sintaxe]] do DokuWiki para saber como o texto pode ser formatado.
-==== Tipografia ====
-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 //[[utils:glossario#p|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.
-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.//
-==== Títulos ====
-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 [[##topicos_principais|tópicos principais]]) pode possuir suas próprias convenções de titulação e organização do conteúdo.
-==== Notas ====
-Essa instância do DokuWiki possui um //plugin// de notas (//[[https://www.dokuwiki.org/plugin:note|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.
-<note>
-Este não é o comportamento padrão do terminal de comandos. Lembre-se de que aqui estamos usando um emulador (gráfico) de terminal, com configurações específicas.
-</note>
-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.
-<note tip>
-Você pode preferir desativar o serviço __sshd__ no seu //Desktop//, afinal tipicamente não vai acessá-lo remotamente.
-</note>
-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.
-<note important>
-Aloque espaço suficiente na partição de //boot//, para evitar problemas durante a instalação ou atualização do sistema, e periodicamente remova os //kernels// mais antigos e em desuso.
-</note>
-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.
-<note warning>
-Não use o diretório __/tmp__ para este processo. Caso haja alguma interrupção acidental (queda de energia, por exemplo), todo o seu trabalho será perdido.
-</note>
-=== Notas tituladas ===
-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:
-<note tip>
-**Fique por dentro!**\\
-\\
-O sistema tipográfico TeX possui em torno de si comunidades vibrantes, que regularmente criam módulos, organizam eventos, publicam materiais sobre o assunto e ajudam a difundir essa tecnologia.\\
-\\
-Para saber mais, você pode querer acompanhar as publicações e notícias no portal [[https://tug.org/|TeX Users Group (TUG)]].
-</note>
-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.
-==== Imagens ====
-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 800x600 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.
-=== Uso de emoticons ===
-A sintaxe do DokuWiki admite o uso de //[[wiki:syntax#text_to_image_conversions|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|tipografia]]).
-  * FIXME
-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:
-> FIXME Detalhar quais predicados são aceitos nesse tipo de consulta.
-==== Tabelas ====
-...
-=== Tabelas de glossário ===
-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:
-^  Buscar por letra                                                                     ^^^^^^^^^^^^^
-|  A  |  B  |  C  |  [[#d|D]]  |  E  |  F  |  G  |  [[#h| H]]  |  [[#i|I]]  |  J  |  K  |  L  |  M  |
-|  [[#n|N]]  |  O  |  P  |  Q  |  [[#r|R]]  |  S  |  T  |  U  |  V  |  W  |  X  |  Y  |  [[#z|Z]]  |
-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 =====
-Convenções de redação dizem respeito ao modo como os tópicos devem ser organizados, e como os textos devem ser construídos.
-==== Tópicos principais ====
-A [[:start|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 [[https://forum.slackjeff.com.br/viewforum.php?f=26|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 [[#convencoes_de_contexto|convenções de contexto]], mais adiante).
-> (Contexto: **[[utils:|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.
-==== Glossários ====
-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 ([[#tabelas|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.
-==== Seções vazias ====
-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.
-> ...
-==== Ortografia e Gramática ====
-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).
-==== Concisão ====
-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.
-=== Tamanho dos parágrafos ===
-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|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.
-==== Termos estrangeiros / estrangeirismos ====
-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.
-===== Convenções de versionamento =====
-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.
-==== Tipos de alteração ====
-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.
-==== Descrição das versões ====
-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 =====
-Convenções de contexto dizem respeito à organização das páginas em termos de aplicação de //namespaces//, um [[https://www.dokuwiki.org/namespaces|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.
-==== Contextos principais ====
-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.
-==== Aninhamento de contextos ====
-...