Padronização da Wiki para a Documentação

De wiki.eliteSoft.com.br
Revisão de 12h17min de 7 de abril de 2020 por Mayara.gundhner (discussão | contribs) (Formatação do texto: refinamento)
Ir para: navegação, pesquisa

« Voltar | « Principal

Versão: 1.0

Padrão para documentação - Web, Desktop, Mobile e Central do Assinante

Objetivo.jpg O objetivo dessa pagina é apresentar a padronização para a realização de toda documentação da Wiki.
Obs.: O código para inserir Logo, Changelog, Permissão, Variável, Alertas e etc, está em comentário oculto na documentação.


Criar uma página

Para criar uma página segue a explicação:

  • Colocar se é modulo Desktop, Web, Mobile ou Central do Assinante.
  • Colocar qual o nome da área/tópico a ser documentada (Atendimento, Financeiro e etc).
  • Colocar o nome da implementação a ser documentada.
  • Após o "|" (pipe) colocar novamente a área e o nome da implementação.
  • Seguir o modelo da imagem abaixo:

CriandoPag.png

Inserir logo EliteSoft

A logo da EliteSoft deverá ser inserida no início da página e centralizado.
Ispintegrator6.png

Botões voltar e principal

Os botão Voltar e Principal deverá ser inseridos para retornar ao primeiro vínculo da página ou a página principal da Wiki.

Tabelas permissões e variáveis

A tabela de permissões e/ou variável deverá ser inserida seguindo o padrão abaixo:

  • Centralizada;
  • Primeira linha em azul (#005694) e letras na cor branca (white);
  • Linhas secundárias na cor cinza (#E8E8E8)
  • Inserir o link da documentação na permissão e na variável.

PermissaoPadronizacao.png VariaveisPadronização.png

Changelog

1) Todas as documentações criadas deveram ter o changelog.

  • Ex: permissões, variáveis, relatórios e etc.

2) Para inserir o changelog deverá seguir os padrões abaixo de acordo com a situação:

  • A frase deve seguir o padrão das imagens abaixo;
  • Nome da atualização e versão changelog em negrito;
  • Na palavra “Changelog e a versão” inserir o link;

Changelog - inicio da documentação

Quando for iniciar uma documentação, segue o modelo:
ChangelogDisponibizado.png

Changelog - alteração

Quando for explicar alguma alteração no changelog , colocar em negrito.
Deverá ser colocado logo acima da alteração a ser explicada.
ChangelogAlteracao.png

Índice

Para inserir o índice segue o código que deverá ser usado:
Ex.: TocIndice.png

Título

Toda documentação deverá ter um título.

  • As primeiras letras em maiúsculo.

Objetivo

Toda documentação deverá ter o objetivo e qual o motivo da implementação.

  • Inserir a imagem demonstrada abaixo e em frente o objetivo;
  • Medida de 30px e do lado esquerdo da página;

ObjetivoPadronizacao.png

Situação problema

Para melhor compreensão apresentar uma "Situação" problema.

  • Apresentar para o cliente uma situação do dia a dia.

SituacaoModelo.png

Imagem

Deverá ser inserida imagem do Integrator para conduta da documentação.

  • Na SVN já tem algumas imagem salvas caso precise: SVN\Qualificação\Imagens + prints
  • Modo de inserir imagem na wiki: https://wiki.elitesoft.com.br/index.php/DocInterna_PoliticaOrg_GuiaInserirImagemWiki
  • A imagem deverá ficar do lado esquerdo da página;
  • Caso a ilustração seja maior que a tela, deverá ser de até 1000 pixels.
  • A imagem deverá ser enquadrada com borda fina de 1px do "Paint" para salientar a representação: ContornoImagem.png
  • A imagem deverá ter ênfase com retângulo nas partes importantes para melhor visualização, nos seguintes casos: ícones, botões, tela dentro de tela:
    • Retângulo, tamanho 3px, cor vermelho. ContornoBotoesItensEtc.png
  • Quando exibir o nome de cliente precisará ofuscar.
  • Quando exibir o foto de cliente ou colaborador substituir por uma foto fictícia.

Obs.: usar a ferramenta https://www.photopea.com

  • A cada explicação/tópico da tela organizar por numeração:

Ex.:
1) explicação,
1.1) Explicação do mesmo assunto e assim sucessivamente,
2) Explicação, etc.

  • Descrever acima da imagem o passo a seguir.
  • Descrever abaixo da imagem o caminho a seguir em caixa alta: Caminho a Seguir: ISP - INTEGRATOR / CADASTRO DE CLIENTES / CARACTERES DE PESQUISA

Tela bloqueada

Para a tela bloqueada deverá inserir acima esta caixa de mensagens para melhor entendimento:
TelaBloaqueadaPadronização.png

Alertas

Deverá inserir a caixa de texto de alerta de acordo com cada situação:

  • Para destacar alerta ou advertência para pontos que não podem ser alterados ou podem ser usados somente da forma que estão, colocar acima da rotina a ser trabalhada:

Alerta0.png

  • Quando é necessário o suporte oferecer o acesso, colocar acima da rotina a ser trabalhada:

Alerta1.png

  • Colocar ao final de cada documentação:

Alerta2.png

Ver também

Quando existir uma pagina que pode ser ligada a outra deverá colocar o titulo Ver também e o link da pagina.

Botão "topo"

Deverá ser inserido no rodapé da pagina o botão “Topo

Categoria

Toda documentação que apresentar changelog, variáveis, permissões ou que for relatório deverá apresentar no final da pagina a Categoria.
Ex: ExemplosDeCategoria.png

Comentário após termino da documentação

Após terminar toda a documentação colocar no começo um comentário, contendo:
<!- - data da finalização da documentação - (número do atendimento) nome do cliente - descrição do atendimento - ->

Formatação do texto

1) Informações para formatação de palavras (negrito, itálico, etc) acesse: https://www.mediawiki.org/wiki/Help:Formatting/pt


2) Proteger a tela criada ou atualizada para que apenas “usuários auto confirmados” (colaboradores da EliteSoft) possam editar.

  • Clicar no botão Mais e em seguida na opção Proteger, abrirá uma novo tela.
  • No campo Editar selecionar a opção Permitir apenas usuários autoconfirmados.


3) Colocar a palavra em negrito quando:

3.1) Quando indicar uma aba:
Ex.: Campo Extra e Editar Campo.

3.2) Quando indicar botão referente à “Ícone” e “Menu” deverá estar em negrito.

3.3) Quando for explicar alteração de um “Campo”, “Tela” ou “Item” deverá estar em negrito.


4) Quando colocar observações deverá:

  • Abreviar e colocar em negrito Obs.
  • Se a for de extrema importância, deverá ser colocada em vermelho.
  • Se mencionar a forma de entrar em contato para adquirir um serviço, deverá colocar em azul.
  • Deverá utilizar as cores padrão da empresa:
    • Azul = 1a428a
    • Vermelho = cf3339
    • Cinza = 636569
    • Azul Claro= 97caeb

PadronizacaoObsCores.png


5) Para novas telas usar o termo “exibirá”, ao invés de “irá exibir”.
Ex.: Exibirá a tela Novo Cliente, no item Validação do Cliente.

5.1) Sempre usar Integrator Desktop/Web/Central do Assinante, com a inicial maiúscula.


6) Palavras em outros idiomas (inglês, espanhol e etc), deixar em itálico.
Obs.: Exceto palavras que não tenham etimologia inglesa, ver https://michaelis.uol.com.br


7) Para radioButton e checkbox usar a expressão “Marcar”.


8) Para selecionar algum botão, usar a expressão:
Ex.: “Selecionar a opção “Salvar” ”.


9) Quando mencionar a palavra mensagem, colocá-la “entre aspas”.
Ex.: Apresentará a mensagem: “mensagem”.


10) Termo para duplo clique: dar um clique duplo.


11) Termo para utilização do botão direito: Clicar com botão direito do mouse.


12) Alinhamento de texto:

  • Os tipos de alinhamento possíveis são: center (centralizar), left (esquerda), right (direita), justify (justificado).


13) Quando for necessário ocultar um comentário, ou seja, mantê-lo somente na página de edição, usar: <!- - Comentário -->.
Obs.: Os caracteres <,!,- devem ser juntos.


14) Numa condição, utilizar a frase: Caso queira, caso necessário ou caso contrário.


15) Utilizar Siglas/ Abreviações/ Acrônimos quando não tiver espaço.
Ex.: Inscrição Estadual: I.E , E-mail (Label e texto corrido)

ANOTAÇÕES IMPORTANTES

Alterar Sidebar: link para fazer a alteração na carra de navegação - http://wiki.elitesoft.com.br/index.php/MediaWiki:Sidebar
Registro de eliminações: link para verificar as eliminações nas páginas ou páginas eliminadas - http://wiki.elitesoft.com.br/index.php/Especial:Registro/delete

Link

1) Não usar acentuação.

2) Utilizar palavras chaves e sem abreviação (para saber do que se trata a documentação).

3) Entre cada palavra, inserir um _ (underline) para produzir link.

Ex.:PadronizacaoExCriarLink.png


Link interno

Para adicionar um link interno, deverá encontrar a página que será reproduzida:


Link externo

Deverá fazer uma cópia do link inteiro e aplicar: Ex.: http://wiki.elitesoft.com.br/index.php/P%C3%A1gina_principal

  • Para criar uma página na documentação interna, é necessário que a página seja criada sem espaços e sem acentuação, devido a restrição.

Ex.: CriandoLink.png

    • Veja que ao acessar a página, o nome da página ficará no padrão.

Ex.: LinkExemplo.png


Link projetos

Modelo: https://wiki.elitesoft.com.br/index.php/Documentações_e_Vídeos_Desk

  • Inserir o nome abreviado com o código, do projeto que está em execução.

Ex.: FC_43 = Ficha Contratada 43 ou AG_5 = Ágil 5

  • Módulo da implementação, palavras juntas e a letra inicial maiúscula para palavras diferentes.

Ex.: ModuloDesk, ModuloWeb.

  • Código do cliente no Integrator.
  • Número do protocolo do atendimento.
  • Descrição da implementação: poderá ser escrito com acentuação e cedilha e palavras separadas por _ (underline) com letra maiúscula para palavras principais.

Acrescentar vídeo do Youtube

1) Para adicionar um link do Youtube no documento, deve-se definir o vídeo que quer anexar e empregar onde está referenciando:
Ex.: VideoYouTube.png

2) Para inserir a imagem e essa imagem chamar o link do Youtube, adicione o link (esta em comentário oculto) para mostrar esta imagem Icfitavideo.png, que será o link do seu documento.

3)Para fazê-lo funcionar basta seguir este exemplo: LinkVideo.png

Toda página pode ter um apelido

1) Todo apelido de página será igual ao link, na mesma linha separadas pelo '"|"'(Pipe) e, qual o projeto, o código do projeto, a descrição (Módulo Desktop, Web, Central do Assinante ou Mobile), o código do cliente, o protocolo de atendimento e a descrição da implementação, todas as palavras separadas por underline (_), terão a seguinte característica:
Ex.: ApelidoPag.png


Histórico de Revisões

Versão Data de Revisão Autor Resumo de Mudanças Aprovação
1.0 12/12/2019 Mayara Gundhner Adicionado Histórico de Revisão, alteração sobre o changelog (adicionar em todas as documentações criadas), caminho das imagens na SVN e sobre categoria



Topo