Diferenças

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

--- wiki:convencoes [2024/12/08 22:15] – [Tipografia] menção ao bloco e itálico 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.
-==== 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.//
-==== 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>
-==== Imagens ====
-...
-==== 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 abranger explicações mais genéricas daquele assunto. Essa seção poderá ser usada, entre outras coisas, para apresentar um //hyperlink// para um glossários de termos daquele tópico (se houver um).
-//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.
-==== Termos estrangeiros x 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 os estrangeirismos, casos em que nos apropriamos de uma palavra estrangeira como se fizesse parte da língua portuguesa. Alguns casos de estrangeirismo são muito comuns e podem ser usados, como //deletar// (apagar). Mas no geral, devem ser evitados, pois haverá quase sempre um termo equivalente em português que transmitirá a mensagem com mais acurácia.
-Exemplo com estrangeirismo:
-> Depois de ajustar as configurações, dê um //refresh// na página.
-Exemplo sem estrangeirismo:
-> 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).
-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**.
-==== Aninhamento de contextos ====
-...