Difference between revisions of "Guia de Estilo"

Revision as of 16:37, 9 August 2011

Artigos da Base de Conhecimento

Esta seção discute a estrutura dos artigos e a sua disposição dentro da Base de Conhecimento, a sua ordenação como um todo.

Estrutura dos Artigos da Base de Conhecimento

Existem basicamente dois tipos de artigo da Base de Conhecimento:

Os que respondem a uma pergunta específica ("Como salvar as texturas no disco rígido")
Os que dão alguma informação geral sobre um tópico ("Guia de Empregos no Second Life")

Em ambos os casos, o primeiro parágrafo do artigo deve responder a uma pergunta não formulada:

Depois que eu li isso, o que devo ser capaz de fazer? (Bastante auto-evidente.)
Depois que eu li isso, o que devo entender melhor?

Isto pode ser tão simples como fazer o primeiro parágrafo dizer algo como: "Este artigo discute ___."

Se todos os artigos na Base de Conhecimento começarem desta forma, os leitores se acostumaram a descobrir muito rapidamente se as informações em um artigo específico lhe será útil, sem ter que ler todo o artigo.

Cabeçalhos

Os artigos devem ser divididos em cabeçalhos, cada um representando um tema distinto. Por exemplo, em um artigo que trata de diferentes tipos de objetos com script, cada um deve ter sua própria seção, com seu cabeçalho, para uma melhor organização da página.

Cabeçalhos de nível superior são o equivalente a um comando "h2" utilizado nos softwares de blogs e em outros sistemas de gerenciamento de conteúdo:

== Cabeçalho ==

Além disso, o conteúdo deve começar na linha seguinte, com cada parágrafo separados por duas quebras de linha (se você usar uma quebra de linha única, o texto continua na mesma linha).

Particularmente em um artigo extenso, deve-se fazer o uso de subcabeçalhos:

== Cabeçalho ==
O texto vai aqui...

=== Subcabeçalho ===
Mais texto aqui...

==== Subcabeçalho ====
Mais observações aqui...

Manter com prioridade, o fluxo principal do artigo. A tabela de conteúdo aparece automaticamente em um artigo que tenha quatro ou mais cabeçalhos, mas se sentir que o artigo seja muito extenso para percorrer, você poderá criar seções separadas em suas próprias páginas, e vinculá-las a página principal.

Ou seja coloque na página principal um pequeno resumo do assunto ou uma chamada e insira um link para a outra página, onde o assunto será mais desenvolvido.

Se você não quiser que um artigo não apresente uma tabela de conteúdo, insira no topo o seguinte código:

__NOTOC__

Para economizar espaço e alinhar a tabela de conteúdo a direita, use o seguinte gabarito:

{{TOCright}}

Note que este gabarito não fica bem se você também usar um gabarito de navegação que flutua para a direita.

Escopo sobre a Base de Conhecimento

Um problema básico que sempre acontece nas wikis é a proliferação de páginas que contêm assuntos semelhantes ou até mesmo duplicados, porém sem interligação (links) entre elas. Este fato ocorre naturalmente com o crescimento da wiki. Isso acontece devido a falta de existência de um planejamento centralizado, capaz de localizar estas páginas e organiza-las.

Quando se trata de documentação do Second Life devemos lembrar, por exemplo, que um FAQ sobre o pagamento de uma propriedade deve estar integrado - ou no mínimo, intimamente ligado - ao artigo principal sobre o pagamento de uma propriedade.

Quando se estabelece uma ligação entra as páginas que tratam de um mesmo assunto, isso vai fornecer aos leitores um melhor caminho para conseguir ajuda, e editores mais experientes devem auxiliar a manter as páginas, ligadas entre sí.

Informações duplicadas em várias páginas aumenta as chances de que essas páginas não sejam atualizadas, à medida que ocorrerem atualizações das informações. Esta duplicidade reduz drasticamente a utilidade da Base de Conhecimento como um todo. Sempre que possível, tente modularizar os artigos para que as que informações sobre um determinado assunto fique apenas em um só lugar, e que fique ligado a outros artigos correlacionados. Dessa forma, você só tem que atualizá-lo apenas uma vez.

Uso do tempo presente

Quando você disser as pessoas o que acontece, quando elas fazerem algo, sempre faça o uso do tempo presente. Por exemplo:

Clique em IM. Abre a janela do IM.

Evite usar:

Clique em IM. A janela do IM será aberta.

(IM = Instant messaging é equivalente ao MI = mensagem instantânea)

Terminologia

Importante: A instância mais próxima de um "glossário oficial" é ajuda do Visualizador 2 que tem embutido um glossário, que usa o conteúdo de Viewerhelp:Glossary.

@@ Line 1: / Line 1: @@
 {{Help/pt|Parent=Style Guide|Wiki=*}}
+{{TOCright}}
+== Artigos da Base de Conhecimento ==
+Esta seção discute a estrutura dos artigos e a sua disposição dentro da Base de Conhecimento, a sua ordenação como um todo.
+=== Estrutura dos Artigos da Base de Conhecimento ===
+Existem basicamente dois tipos de artigo da Base de Conhecimento:
+# Os que respondem a uma pergunta específica ("Como salvar as texturas no disco rígido")
+# Os que dão alguma informação geral sobre um tópico ("Guia de Empregos no Second Life")
+Em ambos os casos, o primeiro parágrafo do artigo deve responder a uma pergunta não formulada:
+# Depois que eu li isso, o que devo ser capaz de fazer? (Bastante auto-evidente.)
+# Depois que eu li isso, o que devo entender melhor?
+Isto pode ser tão simples como fazer o primeiro parágrafo dizer algo como: "Este artigo discute ___."
+Se todos os artigos na Base de Conhecimento começarem desta forma, os leitores se acostumaram a descobrir muito rapidamente se as informações em um artigo específico lhe será útil, sem ter que ler todo o artigo.
 === Cabeçalhos ===