slitaz-doc-wiki-data view pages/pt/guidelines.txt @ rev 89
Update meta folder.
| author | Christopher Rogers <slaxemulator@gmail.com> |
|---|---|
| date | Sun Aug 14 12:36:53 2011 +0000 (2011-08-14) |
| parents | |
| children |
line source
1 ====== Orientações para documentação do SliTaz ======
2 Este documento traz orientações para escrever um artigo wiki e os passos para tornar a documentação do Slitaz atualizada.
4 ===== Mutirão da Documentação =====
6 - Centralizar toda a documentação em http://doc.slitaz.org
7 - Completar a migração do Manual (Handbook) e do Livro de receitas (Cookbook)
8 - Tradução do Manual (Handbook) e do Livro de receitas (Cookbook)
9 - Criar links ou traduzir os artigos wiki do [[http://labs.slitaz.org|site do SliTaz Labs]]
10 - Revisar e atualizar o Manual (Handbook) e o Livro de receitas (Cookbook) para a versão 3.0 do Slitaz
11 - Adicionar novos guias. Uma lista de guias sugeridos já está disponível na [[http://doc.slitaz.org/pt:guides:start| página inicial dos guias]], como uma referência inicial
12 - Revisar e atualizar os guias já existentes
14 ===== Instruções gerais =====
16 * **Adicionar novas páginas** : Sinta-se à vontade para adicionar novas páginas no wiki
17 * __Nomenclatura ou hierarquia de documentação__ : A estrutura da hierarquia de documentação está definida em inglês. Por favor, siga esta padronização, mesmo para as versões em português, para criar páginas. Alguns exemplos:
18 * //pt:handbook:start// : Página inicial do Manual (Handbook)
19 * //pt:handbook:desktop// : "Desktop" é uma página dentro da página inicial do Manual. Todas as páginas do Manual devem ser precedidas pela nomenclatura "pt:handbook:"
20 * //pt:guides:faq// : Todas as páginas dos Guias devem ser precedidas pela nomenclatura "pt:guides". Para criar uma página dentro da "Perguntas mais frequentes" (em inglês, "Frequently Asked Questions", daí a sigla FAQ), simplesmente faça <nowiki> [[faq | FAQ]] </nowiki>. Isto irá criar automaticamente uma página com a nomenclatura pt:guides:faq
21 * //Índice// : Links podem ser utilizados para estabelecer uma estrutura hierárquica
22 * __Adicionar imagens__ : Utilize a barra de ferramentas (no modo edição do wiki) para adicionar imagens em páginas relevantes
23 * **Apagar** : Simplesmente remova todo o conteúdo de uma página para apagá-la
24 * **Revisão** : Cada página deve conter uma "Seção de revisão". Por exemplo, [[#formatação|veja o final desta página]]. Estas seções são somente tabelas do wiki. Sinta-se à vontade para editar estas tabelas e/ou adicionar linhas, traduzi-las para o seu idioma e também copiar e colar a "Seção de revisão" desta página para qualquer outra página do wiki e editá-la de acordo com a página destino
26 ===== Layout da páginas =====
28 As páginas de documentação do SliTaz já trazem alguns estilos predefinidos. Tomando como base estes estilos, nós podemos construir um layout consistente.
30 === FAQ - Perguntas mais frequentes ===
32 Estas instruções são válidas somente para uma página: [[pt:guides:faq|FAQ - Perguntas mais frequentes]].
34 - **Mensagem de erro** - nomeie uma FAQ individual com a descrição mais comum, normalmente a mensagem de erro que é exibida.
35 - **Sintomas** - uma breve descrição do que os usuários devem encontrar quando este FAQ funcionar. Talvez haja mais do que um sintoma. Utilizar a formatação correta para descrever possíveis mensagens na tela, combinações de teclas etc. Uma busca na internet deve resolver o assunto.
36 - **Explicação** - uma explicação não muito técnica da mensagem de erro. Os usuários devem ser capazes de entender o problema e como resolvê-lo de uma forma de alto nível.
37 - **Solução** - como resolver tecnicamente o problema. Incluir breves descrições dos passos que necessitarem de mais do que linhas de comando; isto é importante para entender o que o usuário precisa fazer. Problemas individuais têm soluções ligeiramente diferentes -- utilize vários níveis e marcadores para organizar o conteúdo.
40 === Guias ===
42 Estas instruções são para as páginas com nomenclatura <lang>:guides:<tópico>. Elas descrevem o processo para fazer algo funcionar.
44 - **Introdução** - Resume o artigo
45 - **Modo gráfico**
46 * Instruções - Como utilizar uma ferramenta/programa com interface gráfica (se existir)
47 * Capturas de tela (screenshots) - Uma imagem vale mais que mil palavras
48 - **Modo manual**
49 * Instalação - Define os pacotes necessários e como instalá-los.
50 * Configuração - Explica como configurar arquivos para uso adequado dos pacotes
51 * Resumo - Se possível, resumir todos os comandos em um único script para localização de defeitos
52 - **Exemplos e dicas** - Adicione alguns exemplos e dicas avançadas
53 - **FAQ/Localização de defeitos** - Algumas instruções do tipo "faça você mesmo" ou uma subseção sobre problemas, sintomas, soluções, notas ou um link para uma postagem do fórum. Criar links para as FAQ, se respondidas.
54 - **Referências** - Qualquer bom material de referência na internet. Se não houver nenhum, considere escrever uma mensagem requisitando isso!
56 === Manual (Handbook) ===
58 Estas instruções são para as páginas com nomenclatura <lang>:handbook:<tópico>. Elas trazem um resumo do que o SliTaz oferece para um tópico em particular. São resumos e descrições, e não são guias, então devem conter poucas e simples instruções sobre como iniciar e utilizar o sistema.
60 - **Sinopse** - descreve o conteúdo da página, em termos de abrangência.
61 - **Tópico** - título do assunto que o usuário deseja consultar, por exemplo, "Processamento de imagens" ou "Temas para área de trabalho"
62 - **Corpo do texto** - um resumo do tópico, com links para os Guias relevantes ou páginas externas da internet.
63 - **Dicas** (opcional) - qualquer problema ou dificuldade que o usuário possa enfrentar. Criar links para as "FAQ - Perguntas mais frequentes", se já respondidas, para tópicos no fórum, para páginas externas na internet que resolvam o problema etc.
65 ===== Formatação =====
67 Por favor, utilize a formatação correta sempre que possível. Isto proporciona melhor legibilidade e frequentemente diminui ambiguidades entre comandos que deveriam ser inseridos no modo de edição (input) vs. o modo de exibição (output) etc.
69 * Aprenda a sintaxe de um wiki [[http://doc.slitaz.org/pt:wiki:syntax| aqui]]. Para testar a sintaxe wiki, utilize a página do [[http://doc.slitaz.org/en:guides:playground| Playground]]
71 ----
72 \\
73 ^ Seção de revisão das páginas ^^
74 |Qualidade| Boa |
75 |Revisão | Precisa de revisão |
76 |Prioridade | Média |
77 |Problemas| Adicione um [[http://forum.slitaz.org|link para um tópico no fórum]]|
78 |::: | OU adicione um [[http://labs.slitaz.org/issues |link para um tópico no SliTaz Labs]]|
79 |Como melhorar| Faça sugestões breves, por ex.,|
80 |::: | [[pt:guides:start | Adicione link]]|
81 |::: | Adicione novas linhas como essas ;-) |
82 \\
83 ----