Criar e editar textos no Wiki Seidor é uma atividade simples e não requer perfeição na forma e apresentação, mas a clareza na informação e gramática correta são imprescindíveis. Além disso, a identidade visual na construção do texto, seguindo uma uniformidade, facilita a consulta e manutenção das páginas.
Sendo assim, o objetivo deste guia é servir de referência para a padronização na produção de textos na Wiki Seidor. As regras propostas não são obrigatórias. Há diversos bons métodos de formatação, inclusive a construção deste guia está aberta a todos para sugerir melhorias e ajustes, conforme a necessidade e desenvolvimento de criação.
¶ A Interface
¶ Global
- Navegação Global - Um menu de navegação constante, exibido em todas as páginas. Geralmente consiste em páginas importantes ou links para sites externos.
- Pesquisa Global - Encontre rapidamente uma página realizando uma pesquisa.
- Nova Página - Crie uma nova página.
- Conta - Ações específicas do usuário, como Ver Perfil, Administração e Logout.
¶ Por página
- Ações da Página - Lista de ações na página atual, como Editar, Mover, Excluir, Histórico, etc.
- Navegação - Caminho completo para a página atual. Representa a estrutura da pasta.
- Índice - Seções da página atual. Com base nos cabeçalhos do conteúdo.
- Palavras Chave - Tags associadas à página atual. Veja as páginas relacionadas clicando em uma tag.
- Autor - Veja o autor e a data da última modificação da página.
- Compartilhamento e Impressão - Compartilhando / imprimindo links para a página atual.
- Editar Página/Ações - Menu de acesso rápido para editar ou realizar outras ações na página atual.
¶ Fundamentos
¶ Criar nova página
Para criar uma nova página, clique no botão Nova página, localizado no canto superior direito da página.
A seguinte caixa de diálogo aparecerá:
- Selecione o idioma para o qual criar a página (o local atual é selecionado por padrão).
- Insira o caminho completo para a página que deseja criar.
- O caminho não deve conter espaços (em vez disso, use travessões), nem pontos e consiste em caracteres seguros para URL.
- NÃO coloque uma barra final.
- Você não precisa criar pastas. Insira o caminho completo que deseja criar e as pastas serão criadas automaticamente. Por exemplo, insira universo/planetas/terra, para criar automaticamente as subpastas universo e planetas.
- Clique em Selecionar para continuar.
¶ Selecione um editor
Ao criar uma nova página, você verá a seguinte caixa de diálogo:
O Wiki.js oferece vários editores dependendo do tipo de conteúdo que você deseja escrever ou simplesmente da preferência do usuário. Os desenvolvedores geralmente irão com o editor Markdown, enquanto os usuários não técnicos podem preferir o Editor Visual. No entanto, com o objetivo de padronização, o Markdown é o editor mais recomendado.
¶ Insira os metadados da página
Ao selecionar um editor, será exibida a caixa de diálogo metadados da página:
Insira um título, descrição e tags para sua página.
Por fim, clique em OK para fechar a caixa de diálogo e começar a escrever!
Você sempre pode retornar à caixa de diálogo metadados da página clicando no botão Página, localizado no canto superior direito da página.
¶ Salvar
Sua página não é criada até você clicar no botão Criar (localizado no canto superior direito da página). Ele será salvo e renderizado, após o que você será redirecionado automaticamente para o resultado final. Basta clicar no botão editar para voltar à edição!
¶ Título dos artigos
A escolha do título para um artigo é o primeiro passo na criação de um novo conteúdo.
Dicas
- O título deve descrever o assunto de forma objetiva e sem ambiguidade;
- Siga regras gramaticais. Não há restrições quanto acentuação ou uso de espaço;
- Evite o uso de letras maiúsculas, priorize usá-las se for extremamente necessário;
- Evite pontuar o título com ponto de exclamação (!) ou interrogação (?) isso dificulta a pesquisa;
- Evite duplicidade de títulos. Pesquise antes de criar o título.
¶ Aspectos importantes na construção do título
a) Título longo cansa quem está procurando algo objetivo. Se o artigo é sobre a solução de um erro, procure colocar o código deste erro no título e os pontos principais da mensagem.
b) Se o nome for mal formulado, poderá ser mais difícil encontrá-lo e maior a probabilidade de serem criados artigos diferentes sobre o mesmo assunto.
c) A Wiki não é somente uma base de FAQ (Frequently Asked Question). Logo, os títulos dos artigos não precisam necessariamente ser uma pergunta.
d) Seguir convenções coerentes de nomenclatura dos artigo é essencial para que as links internos sejam simples e eficientes.
¶ Parágrafo introdutório
Todos os artigos demandam um parágrafo com uma breve apresentação do assunto a ser tratado, introduzindo o leitor no tema que será apresentado.
¶ Índice e títulos das seções do artigo
Para dividir um artigo em seções, coloque o título da seção iniciando com a hashtag de acordo com o nível hierárquico, como em:
# Esta é a primeira seção
Para fazer uma "subseção" de segundo nível:
## Texto
Para fazer uma "subseção" de terceiro nível:
### Texto
E assim por diante. A cada nível adicionado, acrescenta-se uma hashtag (#) antes do título escolhido. Então o nível de sessão mais alto está associado a um (01) sinal de hashtag antecedendo o título da sessão, a seguir temos o nível dois com dois sinais de hashtag, depois três e assim por diante até o sexto (06) de profundidade, que é o nível mais profundo que surte efeito no índice e no conteúdo do artigo, depois disso os sinais excedentes não surtem mais efeitos.
Com os títulos formatados desta forma, o índice e conteúdo do artigo serão gerados automaticamente, assim como sua hierarquia, e as palavras usadas nos títulos das seções têm maior relevância nas pesquisas (buscas).
Dicas de formatação de seções
- Usar maiúsculas apenas na primeira letra da primeira palavra ou em nomes próprios;
- Evitar fazer ''links'' dentro dos títulos das seções;
- Evitar criar muitos subtítulos, pois faz o artigo parecer desordenado. Parágrafos curtos e frases soltas geralmente não garantem o seu próprio subtítulo;
- Quando não houver texto suficiente para justificar uma seção ou subseção, é preferível usar texto em negrito ou outras marcas dentro de uma seção em vez de subtítulos.
¶ Inclusão de links
O uso dos links são bem-vindos porque eles ajudam na compreensão ou aprofundam o artigo que está sendo produzido.
Ao escrever sobre um determinado assunto e surgir a necessidade de direcionar o leitor para uma outra página da Wiki da Seidor, os Nomes, Palavras, ou Frases considerados como informação adicional, devem ser colocados entre colchetes e na sequência entre parênteses deve-se colocar o caminho da página desejada.
Desta forma, será feito um link entre esse nome, palavra ou frase no artigo que está sendo editado e um outro artigo com este título.
"Exemplo": Os colaboradores da Seidor estão focados em construir um boa base de conhecimentos para o produto [VTAX.](/SEIDOR_BR/PRODUTOS/4TAX_ON-PREMISE/VTAX)
"Resultado": Os colaboradores da Seidor estão focados em construir um boa base de conhecimentos para o produto VTAX.
Dicas
-
Os links que seguem esta sugestão de nomenclatura têm maior probabilidade de ligarem a artigos já existentes, mas se ainda não existir um artigo sobre esse assunto, torna mais provável a criação de um artigo com nome correto por futuros editores;
-
Se o artigo para o qual você quer criar um link ainda não existe, faça uma pequena busca para verificar: pode ocorrer que o nome do artigo seja ligeiramente diferente do que você digitou. Neste caso vale a pena corrigir o link;
-
Nunca use frases como "clique aqui" para o texto de um link — isto não fornece informação alguma.
Consulte os países que fazem parte do Mercosul no site.
Consulte os países que fazem parte do Mercosul no site, clique aqui para ver o site.
¶ Inserção de mídia
Na Wiki Seidor é possível inserir mídias como imagens e arquivos office. É importante atentar quanto ao posicionamento e o tamanho das imagens, deve-se seguir o bom senso de estética para deixar o artigo claro e agradável ao leitor. Já os arquivos office serão exibidos como um link para download.
Primeiramente é necessário subir a imagem ou arquivo na opção "Inserir mídia" a esquerda do painel de edição. Utilize a opção navegar para selecionar um arquivo disponível em seu dispositivo e clique no botão carregar. O arquivo ficará disponível no repositório de mídias, selecione a mídia desejada e utilize a opção inserir para que ela faça parte do artigo.
Para alinhamento da imagem, ao final, após o parênteses, utilize os comandos:
{.align-left}Para alinhamento à esquerda;{.align-center}Para centralizar;{.align-right}Para alinhamento à direita;
Para ajustar o tamanho da imagem, após a extensão, utilize o sinal de igual (=), o tamanho desejado da imagem seguido da letra X:
Exemplo:
{.align-left}
Dicas
-
Quando há imagens próximas verticalmente, intercale-as, colocando uma de um lado e outra de outro; isso dá um equilíbrio estético e evita parecer que o artigo está "pendendo" para um lado;
-
Sempre que necessário, para um melhor posicionamento das imagens, utilize a opção "Alinhamento da imagem" no repositório de mídias, essa opção deve ser escolhida antes do carregamento.
-
Evite amontoar muitas imagens;
-
Não exagere no tamanho da imagem, prefira utilizar o tamanho padrão.
-
Por regra, as fotografias e os gráficos "devem" ter legendas. No entanto, a legenda pode ser omitida se a própria imagem tiver uma legenda ou se for uma óbvia representação do tema do artigo.
¶ Boas práticas
¶ Ortografia
Escreva as palavras corretamente, não utilize expressões idiomáticas ou gírias.
¶ Termos em outras línguas
Dê preferência para termos no idioma da página que está sendo criada. Para palavras em outras línguas, utilize a formatação "itálica". Assim:
- Sempre faça backup.
¶ Não exagere
Torna-se mais fácil retomar o desenvolvimento de um artigo, por si ou por quem lhe suceder, se não optar por exagerar nas marcações (links — internos ou externos, formatação, etc).
Mesmo com as sugestões apresentadas, o editor deve ter em conta que qualquer marcação irá resultar numa determinada aparência quando for visualizada.
- Padronize. Não personalize.
- Lembre-se que todos devem achar fácil participar.
¶ Correções de artigos
O Wiki é uma espaço de produção de texto de forma colaborativa, portanto respeite as alterações dos colegas, caso elas estejam corretas. A Wiki é de todos e quem ganha com as correções somos todos nós.
¶ Sobre Markdown
Markdown é uma sintaxe usada para padronizar e facilitar formatação de texto na web. Mais informações sobre o uso do Markdown e demais informações sobre a Wiki.js consulte no site.