Manual de como se fazer um manual

Logo IXCsoft.png


Este manual é um norteador de utilização básica do wikitexto.
Para se tornar especialista indico lerem esta lista de discussão.

Introdução

Desenvolvido afim de padronizar a produção de novas páginas IXCwiki, de forma que o conteúdo seja atrativo, relevante e fácil de se acessar.

Este manual está aberto a sugestões.

Criando a página

Método de criação por URL

O processo de criação de página mais coerente é pela URL.

Digite a url global da wiki até o index.php, insira uma barra (/) e digite o nome da página que deseja criar, seguindo o exemplo abaixo:

Url de criação.png

Afim de padronizar a url e evitar caracteres estranhos no meio da mesma, sugiro a criação dela com (_) underline. A wiki interpreta underline como espaço e seta o título da página desta forma:

Exemplo de url.png

Criação de página pelo editor visual

A forma tradicional de criar página também é válida, visto que o link já é criado com underlines no lugar dos espaços.

Digite o nome do título, selecione todo o texto do título e clique no botão de corrente (link) conforme exemplo:

Criação de url.png

Ao clicar no botão de link, a caixa se abre assim:

Caixa link.png

Se a página em questão já existir, ou existir alguma página semelhante, o link que aparece é azul.

Se a página não existe, como no exemplo, o link fica vermelho. Clique em concluído para salvar o link.

Exemplo com o link criado:

Link criado.png

Criação de página pelo editor padrão

Para criar links no editor padrão os passos são os mesmos do editor visual.

Digite o nome do título, selecione todo o texto do título e clique no botão de corrente (link) conforme exemplo:

Criação de url tradicional.png

Ao clicar no botão de link, a caixa se abre assim:

Criação url tradicional 2.png

Exemplo de url criada desta forma:

URL criada no editor tradicional.png

Criando urls manualmente com sintaxe wiki

Ainda existe a opção de inserir manualmente a URL em wikitexto, basta seguir a sintaxe do último exemplo, onde o que está antes do pipe (|) é o link url a ser criado e o que está depois do pipe é o texto do link. Segue exemplo de sintaxe wiki:

[[link url da minha página | nome do meu link]]

Formatando a página

A página deve ter uma introdução, que explique a aplicação prática do que está sendo ensinado no manual.

Defina a estrutura do seu manual e separe cada passo importante com um subtítulo.

Subtítulos com tópicos internos podem ser separados por subníveis de subtítulos. O editor visual nos mostra alguns exemplos:

Subtítulos do editor gráfico.png

Geração de índice

Quando se usa os níveis de subtítulos, você estrutura um índice de página. Cada subnível de menu obedece a formatação de subnível do wikitexto.

Segue exemplo de um bom índice, criado automaticamente pela estrutura de subtítulos adotada na página:

Menu estruturado.png

Formatação de texto

  • Usamos negrito sempre que citamos um caminho de menu do sistema, apontando os submenus com o símbolo maior que (>). Exemplo: acesse o menu Cadastros > Clientes > Clientes. Também usamos negrito quando queremos citar um campo, aba, form ou grid do sistema. Exemplo: Preencha o campo Razão da aba Clientes, que está no form Clientes.
  • Usamos itálico quando citamos parte de um texto de outro autor ou conteúdo, quando queremos dar enfase a uma palavra ou ainda quando queremos usar termos estrangeiros.
  • Usamos underline (sublinhado) quando queremos dar enfase a um ponto ou passo importante do manual. Exemplo: é necessário que se sigam as instruções deste manual para que a nossa wiki fique cada vez melhor.

Usos fora deste padrão devem ser corrigidos.

Mais informações sobre estilos consulte o Livro de estilos

Formatação de imagens

As imagens devem ser prints coerentes do sistema referente ao assunto do manual. Existem inúmeras ferramentas, nativas ou instaláveis, que fazem prints com qualidade.

Forms e Grids Web

Quando se trata de forms e grids, o padrão de formatação que usamos é:

  • Tamanho personalizado - 800px de largura;
  • Sem quadro;
  • Centralizado;
  • Marcações da imagem - seleções de área, flechas e textos - em vermelho.
Mobile

Quando se trata de capturas de tela de celular (app mobile ou outro app de apoio), o padrão que usamos é:

  • Tamanho personalizado - 300px de largura;
  • Sem quadro;
  • Centralizado;
  • Marcações da imagem - seleções de área, flechas e textos - em vermelho.

Veja exemplo de formatação de imagens mobile aqui.

Textos de apoio

Os textos de apoio sempre são antes da imagem, citando após ela como um exemplo, assim como fiz em todas as imagens deste manual.

Exceções

Obs: Existem prints que ficam menores que o padrão 800px. Nesses casos usa-se o tamanho original da imagem. Existem alguns exemplos de imagem em exceção nesta página.

Interligações

As interligações são links internos que deixam a wiki mais rica e envolvente. Sempre que uma informação estiver relacionada a outra grid ou form no IXC, podemos citar as páginas wiki que já foram anteriormente criadas sobre o assunto e interligar na página. Por exemplo, podemos criar aqui uma interligação para a página principal.

Através deste recurso, seu conhecimento do sistema como um todo pode ser demonstrado, e aqui a criatividade é o limite. Visite wikis para ver exemplos práticos.

Revisão ortográfica

É muito importante que se revise o conteúdo antes de postar ele. Criei um checklist para servir de base de revisão:

  • Confira títulos;
  • Confira interligações - se estão apontando para o caminho correto;
  • Confira acentuação e sintaxe, se o que escreveu é coerente. Pense sempre que nosso cliente vai ler o seu texto.

Rodapé

O rodapé tem um padrão estabelecido que é a assinatura do desenvolvedor e na linha abaixo a volta para a página pai do manual.

Em casos de revisão, o nome do responsável deve ir abaixo do nome do autor da wiki.

É liberado o uso de ~~~ para assinar os artigos. O resultado desta anotação wikitexto é Je4nPw (discussão).

Criar o caminho para a página pai corretamente. Por exemplo - clientes volta para a página cadastro, e não para a página principal.

Rodapé padrão

Segue exemplo visual de rodapé padrão:

-

Desenvolvido por Je4nPw (discussão)

Revisado por Je4nPw (discussão)

-

Voltar para a Página principal

Rodapé alternativo

Segue exemplo de alternativa ao rodapé padrão (também é aceito):

Desenvolvido por Je4nPw (discussão) 08h53min de 6 de outubro de 2018 (-03)

Revisado por Je4nPw (discussão) 08h53min de 6 de outubro de 2018 (-03)

-

Voltar para a Página principal