rev |
line source |
slaxemulator@3
|
1 ====== Orientações para documentação do SliTaz ======
|
slaxemulator@3
|
2 Este documento traz orientações para escrever um artigo wiki e os passos para tornar a documentação do Slitaz atualizada.
|
slaxemulator@3
|
3
|
slaxemulator@3
|
4 ===== Mutirão da Documentação =====
|
slaxemulator@3
|
5
|
slaxemulator@3
|
6 - Centralizar toda a documentação em http://doc.slitaz.org
|
slaxemulator@3
|
7 - Completar a migração do Manual (Handbook) e do Livro de receitas (Cookbook)
|
slaxemulator@3
|
8 - Tradução do Manual (Handbook) e do Livro de receitas (Cookbook)
|
slaxemulator@3
|
9 - Criar links ou traduzir os artigos wiki do [[http://labs.slitaz.org|site do SliTaz Labs]]
|
slaxemulator@3
|
10 - Revisar e atualizar o Manual (Handbook) e o Livro de receitas (Cookbook) para a versão 3.0 do Slitaz
|
slaxemulator@3
|
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
|
slaxemulator@3
|
12 - Revisar e atualizar os guias já existentes
|
slaxemulator@3
|
13
|
slaxemulator@3
|
14 ===== Instruções gerais =====
|
slaxemulator@3
|
15
|
slaxemulator@3
|
16 * **Adicionar novas páginas** : Sinta-se à vontade para adicionar novas páginas no wiki
|
slaxemulator@3
|
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:
|
slaxemulator@3
|
18 * //pt:handbook:start// : Página inicial do Manual (Handbook)
|
slaxemulator@3
|
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:"
|
slaxemulator@3
|
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
|
slaxemulator@3
|
21 * //Índice// : Links podem ser utilizados para estabelecer uma estrutura hierárquica
|
slaxemulator@3
|
22 * __Adicionar imagens__ : Utilize a barra de ferramentas (no modo edição do wiki) para adicionar imagens em páginas relevantes
|
slaxemulator@3
|
23 * **Apagar** : Simplesmente remova todo o conteúdo de uma página para apagá-la
|
slaxemulator@3
|
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
|
slaxemulator@3
|
25
|
slaxemulator@3
|
26 ===== Layout da páginas =====
|
slaxemulator@3
|
27
|
slaxemulator@3
|
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.
|
slaxemulator@3
|
29
|
slaxemulator@3
|
30 === FAQ - Perguntas mais frequentes ===
|
slaxemulator@3
|
31
|
slaxemulator@3
|
32 Estas instruções são válidas somente para uma página: [[pt:guides:faq|FAQ - Perguntas mais frequentes]].
|
slaxemulator@3
|
33
|
slaxemulator@3
|
34 - **Mensagem de erro** - nomeie uma FAQ individual com a descrição mais comum, normalmente a mensagem de erro que é exibida.
|
slaxemulator@3
|
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.
|
slaxemulator@3
|
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.
|
slaxemulator@3
|
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.
|
slaxemulator@3
|
38
|
slaxemulator@3
|
39
|
slaxemulator@3
|
40 === Guias ===
|
slaxemulator@3
|
41
|
slaxemulator@3
|
42 Estas instruções são para as páginas com nomenclatura <lang>:guides:<tópico>. Elas descrevem o processo para fazer algo funcionar.
|
slaxemulator@3
|
43
|
slaxemulator@3
|
44 - **Introdução** - Resume o artigo
|
slaxemulator@3
|
45 - **Modo gráfico**
|
slaxemulator@3
|
46 * Instruções - Como utilizar uma ferramenta/programa com interface gráfica (se existir)
|
slaxemulator@3
|
47 * Capturas de tela (screenshots) - Uma imagem vale mais que mil palavras
|
slaxemulator@3
|
48 - **Modo manual**
|
slaxemulator@3
|
49 * Instalação - Define os pacotes necessários e como instalá-los.
|
slaxemulator@3
|
50 * Configuração - Explica como configurar arquivos para uso adequado dos pacotes
|
slaxemulator@3
|
51 * Resumo - Se possível, resumir todos os comandos em um único script para localização de defeitos
|
slaxemulator@3
|
52 - **Exemplos e dicas** - Adicione alguns exemplos e dicas avançadas
|
slaxemulator@3
|
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.
|
slaxemulator@3
|
54 - **Referências** - Qualquer bom material de referência na internet. Se não houver nenhum, considere escrever uma mensagem requisitando isso!
|
slaxemulator@3
|
55
|
slaxemulator@3
|
56 === Manual (Handbook) ===
|
slaxemulator@3
|
57
|
slaxemulator@3
|
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.
|
slaxemulator@3
|
59
|
slaxemulator@3
|
60 - **Sinopse** - descreve o conteúdo da página, em termos de abrangência.
|
slaxemulator@3
|
61 - **Tópico** - título do assunto que o usuário deseja consultar, por exemplo, "Processamento de imagens" ou "Temas para área de trabalho"
|
slaxemulator@3
|
62 - **Corpo do texto** - um resumo do tópico, com links para os Guias relevantes ou páginas externas da internet.
|
slaxemulator@3
|
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.
|
slaxemulator@3
|
64
|
slaxemulator@3
|
65 ===== Formatação =====
|
slaxemulator@3
|
66
|
slaxemulator@3
|
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.
|
slaxemulator@3
|
68
|
slaxemulator@3
|
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]]
|
slaxemulator@3
|
70
|
slaxemulator@3
|
71 ----
|
slaxemulator@3
|
72 \\
|
slaxemulator@3
|
73 ^ Seção de revisão das páginas ^^
|
slaxemulator@3
|
74 |Qualidade| Boa |
|
slaxemulator@3
|
75 |Revisão | Precisa de revisão |
|
slaxemulator@3
|
76 |Prioridade | Média |
|
slaxemulator@3
|
77 |Problemas| Adicione um [[http://forum.slitaz.org|link para um tópico no fórum]]|
|
slaxemulator@3
|
78 |::: | OU adicione um [[http://labs.slitaz.org/issues |link para um tópico no SliTaz Labs]]|
|
slaxemulator@3
|
79 |Como melhorar| Faça sugestões breves, por ex.,|
|
slaxemulator@3
|
80 |::: | [[pt:guides:start | Adicione link]]|
|
slaxemulator@3
|
81 |::: | Adicione novas linhas como essas ;-) |
|
slaxemulator@3
|
82 \\
|
slaxemulator@3
|
83 ----
|