Manual de Documentação

Esta página reúne as informações referentes à criação de páginas, formatação e linguagem de marcação Wiki e modelo de documentação de produtos na WikiVoalle.

Como Criar uma Página Wiki

-em construção-

Formatação

Nesta seção, são apresentadas algumas orientações quanto a formatação e padronização do texto na WikiVoalle.

Forma de Escrita

Para uma comunicação clara e objetiva com o usuário, é importante seguirmos algumas orientações:

1. Use frases na ordem direta (sujeito + verbo + complemento).

Exemplo:

Ordem Direta: O atendente explicou o conceito para o cliente.

Ordem Indireta: O conceito foi explicado para o cliente pelo atendente.

2. Busque sinônimos para palavras difíceis.

Dica: acesse https://www.sinonimos.com.br/

3. Use voz imperativa (ordem) na segunda pessoa do singular (você): deve, faça, preencha, siga.

Exemplo:

Voz Imperativa - 2ª pessoa: "Você deve..."

Voz Imperativa - 3ª pessoa: "O usuário deve..."

4. Escreva no tempo presente, e não futuro.

Tempo Presente: “No campo Tipos, você limita quais tipos de solicitações...”

Tempo Futuro: “No campo Tipos, você limitará quais tipos de solicitações...”

Formatação Wiki

Para a escrita do texto, a Wiki permite duas formas de visualização: Edição Visual e Edição de Código Fonte. Através da Edição de Código Fonte, você deve observar os padrões de formatação da linguagem própria da Wiki: Wiki Markup. Abaixo, serão descritas as formatações utilizadas pelos nossos padrões de texto. Para aprofundar-se sobre WikiMarkup, acesse MediaWiki - Formatação

Rotinas

Escreva as rotinas sempre em itálico, com a inicial maiúscula + espaço + barra.

Exemplo:

Suíte / Cadastros / Equipes

Ao editar seu texto no modo Edição de Código Fonte, é possível indicar um texto em itálico com a utilização de apóstrofos antes e depois do texto, conforme o exemplo.

Exemplo:

 ''Este texto será exibido em itálico''

Títulos

Para manter a hierarquia do texto, é importante utilizar a configuração de níveis de títulos, disponível através do painel de edição do texto. Por padrão, o título da página é automaticamente configurado como nível 1.

Principais: devem ser configurados como Nível 2

Secundários: devem ser configurados como Nível 3

e na mesma lógica, sucessivamente, até o nível 6.

Para e edição, selecione o título, clique em "Cabeçalho" e selecione qual o nível desejado.

Exemplo:

<imagem-print-editor-texto>

Ao editar seu texto no modo Editor de Código Fonte, é possível também indicar o nível através da inserção do símbolo "=" antes e depois do texto.

Exemplo:

==Este é um título principal de nível 2==

===Este é um título principal de nível 3===

====Este é um título principal de nível 4====

=====Este é um título principal de nível 5=====

======Este é um título principal de nível 6======

Processos e Passos

Para indicar instruções de processos ou passos, construa o texto no formato de listagem numérica, grifando os numerais com negrito.

Exemplo:

<Imagem-lista-numerica>

Ao editar seu texto no modo Edição de Código Fonte, indique uma listagem numérica com a inserção do símbolo # no início de cada item, conforme o exemplo.

Exemplo:

# item número 1
# item número 2
## coloque dois sustenidos para indicar o item 2.1
### coloque três sustenidos indicar o item 2.1.1

O resultado será:

item número 1
item número 2
1. coloque dois sustenidos para indicar o item 2.1
  1. coloque três sustenidos indicar o item 2.1.1

Campos e Preenchimentos

Para indicar instruções sobre campos que devem ser preenchidos, construa o texto no formato de listagem de itens, grifando os itens com "bolinha".

Ao editar seu texto no modo Edição de Código Fonte, indique uma listagem de itens através da inserção do símbolo * no início de cada item, conforme o exemplo:

Exemplo:

*item número 1
** coloque dois asteriscos para indiciar um subitem
*item número 2
::- coloque dois dois pontos e um hífen para um subitem grifado com hífen.

O resultado será:

item número 1
- coloque dois asteriscos para indiciar um subitem
item número 2

- coloque dois dois pontos e um hífen para um subitem grifado com hífen.

Ícones

Ícones são amplamente utilizados em nosso sistema como partes de botões, indicadores, entre outros. Nosso sistema utiliza três bibliotecas diferentes para ícones. Ao descrever elementos como botões, indicadores, entre outros em seu texto, será necessário também referenciar o ícone deste elemento. Para isso, é necessário fazer sua importação para a Wiki:

1. Primeiro, descubra o nome e a qual biblioteca este ícone pertence.

Google Icons

Biblioteca oficial de ícones do Google. Normalmente utilizados em rotinas desenvolvidas em React (desenvolvidas ou migradas para nova tecnologia).

https://icon-sets.iconify.design/ic/

FontAwesome4

Normalmente utilizados em rotinas desenvolvidas em PHP (antigas)

https://icon-sets.iconify.design/fa/

Material Design Icons

Biblioteca da comunidade, baseada na biblioteca oficial do Google. Normalmente utilizados em rotinhas em React (desenvolvidas ou migradas para nova tecnologia).

https://icon-sets.iconify.design/mdi/

💡 Dica: É sempre válido perguntar para o desenvolvedor ou designer da rotina qual foi o ícone e de qual biblioteca este é antes de iniciar a busca.

Exemplo:

Ícone "play", utilizado na rotina Suíte / Minhas Tarefas '

1. Primeiro, descubra o nome e a qual biblioteca este ícone pertence.

2. Sabemos que seu nome é "play", e que provavelmente é da biblioteca "FontAwesome4" por ser uma rotina em PHP.

3. Com o nome do ícone, busque-o na barra de pesquisa das bibliotecas e compare se o que foi encontrado é de fato o que foi utilizado em nossos sistema.

4. Selecione-o e altere sua altura (campo height) para 24px;

5. Encontrado e formatado , basta copiar seu código de importação e colá-lo em seu texto na Wiki.

<span class="iconify" data-icon="fa:play" style="font-size: 24px;"></span>

6. Os ícones importados virão na cor preta por padrão. Para alterar a cor conforme nosso sistema, é necessário identificar a cor utilizada e inserir o seguinte trecho de código dentro do código copiado da biblioteca:

style="color: #004566"

Neste exemplo, a cor azul padrão do ERP é representada pelo seu código hexadecimal:

#004566

O código ficará assim:

<span class="iconify" data-icon="fa:play" style="font-size: 24px;" style="color:#004566"></span>

E o resultado será:

Pronto! O ícone foi inserido no seu texto. =)

Quebras de Linha

Para manter a estruturação do seu texto dentro da formatação da wiki, a utilização de quebras de linha é necessária. Sempre ao fim de uma frase ou item, adicione o enter. Basta clicar no ícone da imagem abaixo e a tag
será inserida ao final da frase, indicando a quebra de linha.

Exemplo:

Para que o texto quebre (pule a linha),
ao fim de cada frase
insira este pequeno pedaço de código.

Para este resultado, o texto foi escrito assim:

::Para que o texto quebre (pule a linha), <br> ao fim de cada frase <br> insira este pequeno pedaço de código.

Modelo de Documentação

As rotinas do sistema são documentadas seguindo a seguinte estrutura padrão:

1. Rotina
    1.1 Objetivos da Rotina
    1.2 Utilização da Rotina
2. Principais Conceitos
    - Conceito A
3. Requisitos
4. Visão Geral
    4.1 Funcionalidades
5.Ações da Rotina
    5.1Ação 01
6.Rotinas Relacionadas

Na formatação HTML utilizada na wiki, a estrutura é a seguinte:

==Rotina==
===Objetivos da Rotina===
===Utilização da Rotina===
==Principais Conceitos==
'''Conceito A''':
==Requisitos==
==Visão Geral==
===Funcionalidades===
==Ações da Rotina==
===Ação 01===
==Rotinas Relacionadas==

Rotina

A seção rotina é composta por uma breve descrição, "Objetivos da Rotina" e "Utilização da Rotina". Na descrição, aponte onde esta rotina será encontrada no sistema.

Exemplo:

A rotina "Cadastro de Equipes" faz parte da seção "Cadastros" do Módulo Suíte do ERPVoalle.

Seu caminho é: ERPVoalle / Suíte / Cadastros / Equipes

Em "Objetivos da Rotina" descreva de forma sucinta e objetiva a que esta se destina. Comece o texto com um verbo no infinitivo.

Exemplo:

Objetivos da Rotina:

Possibilitar o cadastro, edição e exclusão de equipes.

Em "Utilização da Rotina", aponte onde esta rotina será utilizada e também onde terá impacto, e qual será este impacto.

Exemplo:

Utilização da Rotina:

As Equipes cadastradas nesta rotina serão utilizadas nos cadastros de pessoas (ERPVoalle / Suíte / Cadastros / Pessoas - completo), em Parâmetros e Configurações de Solicitações.

Ao editar seu texto no modo Edição de Código Fonte, este trecho deverá ser escrito assim:

==Rotina==
A rotina "''Cadastro de Equipes''" faz parte da seção "''Cadastros''" do Módulo Suíte do ERPVoalle. <br>
Seu caminho é: ''ERPVoalle / Suíte / Cadastros / Equipes''

===Objetivos da Rotina===
Possibilitar o cadastro, edição e exclusão de equipes.

===Utilização da Rotina===
As Equipes cadastradas nesta rotina serão utilizadas nos cadastros de pessoas (''ERPVoalle / Suíte / Cadastros / Pessoas - completo''), em Parâmetros e Configurações de Solicitações.

Principais Conceitos

Nesta seção serão elencados os conceitos utilizados nesta rotina, de forma a facilitar o entendimento das suas funcionalidades, impacto e do próprio sistema ERPVoalle.

💡 Para esta seção, é importante a construção de um Glossário, onde os termos relevantes sejam centralizados e sirva também como base de consulta.

Descreva os conceitos seguindo a formatação do exemplo abaixo:

Principais Conceitos

Para o melhor entendimento da rotina, abaixo estão listados os conceitos aqui utilizados:

Área: Refere-se aos setores que a empresa cria para organizar e estruturar o trabalho de acordo com o tipo e tamanho de atividade que ela executa. Cada área tem suas particularidades e funções específicas, que auxiliam no melhor desempenho de uma empresa.

Equipe: Agrupador de pessoas, em que os integrantes são os colaboradores e a gestão é realizada por uma liderança. Cada equipe é responsável por determinadas funções de um setor, além de possuir suas próprias regras, permissões, gerentes e integrantes (mesmo que uma mesma pessoa possa estar em várias equipes).

Local: No ERPVoalle, o Local identifica a Empresa, ou seja: cada CNPJ (Cadastro Nacional da Pessoa Jurídica) é um Local. Caso a Empresa tenha mais de um CNPJ, cada um deles terá um Local exclusivo nos parâmetros do ERPVoalle.

Permanência SLA: É o número de horas que as solicitações podem permanecer na equipe.

Ao editar seu texto no modo Edição de Código Fonte, utilize a seguinte formatação:

==Principais Conceitos==
Para o melhor entendimento da rotina, abaixo estão listados os conceitos aqui utilizados:<br>

'''Área''': Refere-se aos setores que a empresa cria para organizar e estruturar o trabalho de acordo com o tipo e tamanho de atividade que ela executa. Cada área tem suas particularidades e funções específicas, que auxiliam no melhor desempenho de uma empresa.

'''Equipe''': Agrupador de pessoas, em que os integrantes são os colaboradores e a gestão é realizada por uma liderança. Cada equipe é responsável por determinadas funções de um setor, além de possuir suas próprias regras, permissões, gerentes e integrantes (mesmo que uma mesma pessoa possa estar em várias equipes).

'''Local''': No ''ERPVoalle'', o Local identifica a Empresa, ou seja: cada CNPJ (Cadastro Nacional da Pessoa Jurídica) é um Local. Caso a ''Empresa'' tenha mais de um CNPJ, cada um deles terá um ''Local'' exclusivo nos parâmetros do ''ERPVoalle''.

'''Permanência SLA''': É o número de horas que as solicitações podem permanecer na equipe.

Requisitos

Nesta seção, deverão ser indicados quais os requisitos para que a rotina possa ser utilizada ou configurada. Construa seu texto seguindo a estrutura "Para que seja possível <objetivo>, antes é necessário:", elencando os requisitos em itens.

Exemplo:

Requisitos

Cadastrar as pessoas que serão integradas à equipe, com os atributos corretos (colaborador, supervisor...) através da rotina Suíte / Cadastros / Pessoas - Completo;

Cadastrar os Locais, ou seja, as Empresas - através da rotina Suíte / Cadastros / Locais;

Definir as regras da equipe: se terá restrições no acesso ao sistema; se os integrantes poderão encerrar solicitações; para quais equipes poderá encaminhar solicitações.

Ao editar seu texto no modo Edição de Código Fonte, utilize a seguinte formatação:

==Requisitos==
Para que seja possível cadastrar e configurar uma Equipe, antes é necessário:<br>

* Cadastrar as pessoas que serão integradas à equipe, com os atributos corretos (colaborador, supervisor...) através da rotina ''Suíte / Cadastros / Pessoas - Completo'';<br>

* Cadastrar os Locais, ou seja, as ''Empresas'' - através da rotina ''Suíte / Cadastros / Locais'';<br>

* Definir as regras da equipe: se terá restrições no acesso ao sistema; se os integrantes poderão encerrar solicitações; para quais equipes poderá encaminhar solicitações.

Visão Geral

Aqui, você deve inserir apenas uma captura de tela da rotina indicando os principais botões, sem textos explicativos, conforme a figura abaixo.

Instruções para a captura da tela

1. Acesse a rotina através da base de testes.

2. Ative no seu navegador (Chrome) as Ferramentas de Desenvolvedor através do atalho F12 ou Ctrl + Shift + i . A janela será modificada e apresentará a barra de controle de responsividade.

3. Altere os valores para 1366x768 na barra superior, conforme a imagem abaixo. Estes valores indicam a proporção de tela que será visualizada.

4. No menu da Barra de Responsividade, selecione a opção "Fazer captura de tela"

5. Utilize esta imagem para identificar os elementos da tela de acordo com seu texto de ajuda (tooltip).

6. Exporte como um arquivo .png e insira em seu texto, com a legenda da imagem seguindo a formatação: "visao-geral-<rotina>"

Exemplo:

visao-geral-rotina-suite-cadastros-equipes

Funcionalidades

É importante que as funcionalidades padrão da rotina sejam apresentadas para o usuário. Para tal, basta inserir o seguinte texto:

Resumo da Rotina: Aqui você vê informações sobre as principais funções da rotina.

Ajuda da Rotina: Ao clicar no ícone, você é direcionado à pagina da Wiki com o conteúdo sobre a rotina.

Filtro Avançado: Utilize filtros para buscar itens da rotina.

Pesquisar: Faça uma pesquisa livre por palavras e itens da rotina.

Ao editar seu texto no modo Edição de Código Fonte, ele se parecerá assim:

<span class="iconify" data-icon="ic:baseline-school" style="color: #004566; font-size: 24px;"></span> Resumo da Rotina: Aqui você vê informações sobre as principais funções da rotina.

<span class="iconify" data-icon="ic:baseline-support" style="color: #FF7300; font-size: 24px;"></span>Ajuda da Rotina: Ao clicar no ícone, você é direcionado à pagina da Wiki com o conteúdo sobre a rotina.

<span class="iconify" data-icon="ic:baseline-filter-alt" style="color: #004566; font-size: 24px;"></span>Filtro Avançado: Utilize filtros para buscar itens da rotina.

<span class="iconify" data-icon="ic:outline-search" style="color: #004566; font-size: 24px;"></span>Pesquisar: Faça uma pesquisa livre por palavras e itens da rotina.

Ações da Rotina

Aqui você deve descrever todas as ações e processos que podem ser executados na rotina. Os títulos devem ser claros, utilizando palavras-chave do que será explicado, obedecendo o seguinte formato:

Como + verbo + o que

Exemplo:

'Como adicionar integrantes à equipe

Descreva as ações da rotina seguindo a formatação do exemplo abaixo:

Clique no botão Criar Novo Registro;
Na janela que será exibida, insira as informações necessárias nos campos, respeitando as obrigatoriedades de preenchimento. Na aba "Detalhes", siga os seguintes passos:
- No campo Código, preencha com um número para classificação e ordenação do cadastro;
- Em Equipe, dê um nome à equipe;
- Em Local, informe a empresa à qual a equipe está vinculada;
- No campo Área, informe área à qual a equipe está vinculada;
- No campo Gerente da Equipe, diga qual pessoa responsável pela equipe. Para que uma pessoa possa ser gerente de uma equipe, ela deve estar ativa, não bloqueada e ter o atributo “supervisor” marcado em seu cadastro, na rotina Suíte / Cadastros / Pessoas - Completo.
- Caso queira que os integrantes da equipe possam encerrar solicitações, marque o campo Integrante Encerra.
- Quando marcado o campo Relato Privado, os relatos de solicitação serão privados por padrão (com a possibilidade de alteração em cada relato).
- No campo Restrição de Horário, você restringe o acesso dos integrantes ao sistema a determinados dias e horários. Caso marque “Sim”, será habilitado o menu "Horários", para configuração.
Caso você tenha marcado "Sim" no campo Restrição de Horário, veja abaixo o que fazer. Caso contrário, pule para o Passo 4.
Em Tipo de Restrição, diga se aquele dia será "Restrito" ou "Liberado". Quando selecionado "liberado", os campos de hora inicial e final serão de preenchimento obrigatório. Os integrantes da equipe só conseguirão acessar o sistema nos dias marcados como Liberados, e nos respectivos horários.
- Nos campos Hora Inicial e Hora Final, determine os horários inicial e final em que o acesso ao sistema estará liberado naquele dia da semana. É possível adicionar quantos horários desejar, assim como excluir algum já cadastrado.
Clique no botão "Salvar Novo"
Sua equipe foi criada. Agora, você deve utilizar as ferramentas da coluna "Ações" para adicionar ou editar outras informações deste cadastro, relacionadas a integrantes, permanência SLA, tipos de solicitações e encaminhamento.

Ao editar seu texto no modo Edição de Código Fonte, utilize a seguinte formatação:

==Ações da Rotina==
Abaixo, as instruções para a execução de algumas ações nesta rotina.

===Como cadastrar uma nova Equipe===
#Clique no botão <span class="iconify" data-icon="ic:baseline-add-circle" style="color: #004566; font-size: 24px;"></span>'''Criar Novo Registro''';
#Na janela que será exibida, insira as informações necessárias nos campos, respeitando as obrigatoriedades de preenchimento. Na aba "Detalhes", siga os seguintes passos:
#*No campo ''Código'', preencha com um número para classificação e ordenação do cadastro;
#*Em ''Equipe'', dê um nome à equipe;
#*Em ''Local'', informe a empresa à qual a equipe está vinculada;
#*No campo ''Área'', informe área à qual a equipe está vinculada;
#*No campo ''Gerente da Equipe'', diga qual pessoa responsável pela equipe. Para que uma pessoa possa ser gerente de uma equipe, ela deve estar ativa, não bloqueada e ter o atributo “supervisor” marcado em seu cadastro, na rotina ''Suíte / Cadastros / Pessoas - Completo''.
#*Caso queira que os integrantes da equipe possam encerrar solicitações, marque o campo ''Integrante Encerra''.
#*Quando marcado o campo ''Relato Privado'', os relatos de solicitação serão privados por padrão (com a possibilidade de alteração em cada relato).
#*No campo ''Restrição de Horário'', você restringe o acesso dos integrantes ao sistema a determinados dias e horários. Caso marque “Sim”, será habilitado o menu "Horários", para configuração.
#Caso você tenha marcado "Sim" no campo ''Restrição de Horário'', veja abaixo o que fazer. Caso contrário, pule para o Passo 4.
#Em ''Tipo de Restrição'', diga se aquele dia será "Restrito" ou "Liberado". Quando selecionado "liberado", os campos de hora inicial e final serão de preenchimento obrigatório. Os integrantes da equipe só conseguirão acessar o sistema nos dias marcados como ''Liberados'', e nos respectivos horários.
#*Nos campos ''Hora Inicial'' e ''Hora Final'', determine os horários inicial e final em que o acesso ao sistema estará liberado naquele dia da semana. É possível adicionar quantos horários desejar, assim como excluir algum já cadastrado.
#Clique no botão "Salvar Novo"
#Sua equipe foi criada. Agora, você deve utilizar as ferramentas da coluna "Ações" para adicionar ou editar outras informações deste cadastro, relacionadas a integrantes, permanência SLA, tipos de solicitações e encaminhamento.

Rotinas Relacionadas

Nesta seção, são listadas as rotinas que se relacionam com a rotina que está sendo documentada. Liste as rotinas conforme o caminho dentro do sistema.

Exemplo:

Cadastro de Equipes

Suíte / Cadastros / Equipes

Cadastro de Pessoas

Suíte / Cadastros / Pessoas - Completo

Para adicionar um link de uma página interna da wiki a um texto, é necessária a utilização da formatação para WikiLinks. Esta formatação é composta pelo nome da página(o texto após a barra no link do navegador) entre duas chaves.

Exemplo:

Cadastro de Equipes

Suíte / Cadastros / Equipes

Cadastro de Pessoas

Suíte / Cadastros / Pessoas_-_Completo

Ao editar seu texto no modo Edição de Código Fonte, utilize a seguinte formatação:

==Rotinas Relacionadas==
'''Cadastro de Equipes'''<br>
''Suíte / Cadastros / [[Equipes]]''

'''Cadastro de Pessoas'''<br>
''Suíte / Cadastros / [[Pessoas_-_Completo]]''

Modelo de Documento

Na página Modelo de Documento você encontra estas indicações de formatação aplicadas. Em caso de dúvidas, entre em contato.