Padrões para Elaboração da Documentação do Produto Sistema de Gestão da Qualidade

Transcrição

1 Página 1 de 15 Sumário 1. INSTRUÇÕES GERAIS BOLETIM DE EVOLUÇÃO TUTORIAL AJUDA GUIA DE ATUALIZAÇÃO DA VERSÃO... Erro! Indicador não definido. 6. CONFIGURAÇÕES ESSENCIAIS REFERÊNCIAS... 14

2 Página 2 de INSTRUÇÕES GERAIS As instruções abaixo informadas são necessárias para orientação do conteúdo a ser estruturado. Devese levar em conta, além dessas instruções, a coesão e coerência da escrita, de forma que melhor oriente o usuário na utilização do sistema. INSTRUÇÕES Idioma Português Fonte para Arial 10 texto Fonte para Arial 14 título Fonte para Arial 12 subtítulo Cor da Preto acinzentado composto pela combinação de cores: Vermelho: 69, Verde: 69, Azul 69 fonte de texto Cor da fonte para títulos e subtítulos *Exceto para títulos da Ajuda, pois ela é de cor branca. Azul composto pela combinação de cores: Vermelho 31, Verde 73 e Azul 125

3 Parágrafo para Boletim de Evolução e Ajuda Página 3 de 15 Exemplo: Marcador padrão Numerador padrão Padrão para nome de (bolinha). OBS.: Evite o uso de marcadores em substituição a dados que necessitem de passo a passo. Neste caso, utilize numeradores. Evite utilizar três níveis de numeração. Ex.: 1.1.1) A melhor sugestão é usar até o 2º nível (1.1) no máximo. Utilize apenas quando estritamente necessário. O nome dos itens (tela, campo, botões, rotina etc) deve ser apresentado em negrito. Ex.: botão Cancelar. Se o texto estiver muito carregado de palavras em negrito, verifique quais das palavras merecem maior

4 itens (funções) e rotinas Nome de itens com palavras incompletas Palavraschave Orientações gerais Página 4 de 15 destaque e negrite apenas elas. Ex.: Em situações como código e parâmetro e código e descrição de rotinas, usar negrito apenas no código. Informe o item como é apresentado no sistema. Se a palavra estiver incompleta, comece informando o seu significado e em seguida o nome do item. Ex.: 1) Informe o percentual do lucro no campo Per. Luc.. Insira palavras-chave, que são palavras que resumem os temas principais de um texto. É um termo que identifica ideias e temas de especial importância para servir de referência à pesquisas. Um único parágrafo pode conter várias palavras-chave. 1) Lembre-se quem é o seu público (interno ou externo). Mantenha o contexto do usuário. Para o público técnico, informações técnicas podem ser utilizadas. Para público usuário externo não deve ser utilizada informação técnica. 1.1) Saiba o nome do item antes de descrevê-lo. Substitua a palavra grid por planilha. Grid é uma informação técnica. 2) Informações duplicadas não devem existir. 3) 3) As correções a serem implementadas no sistema não podem ser citadas ou referenciadas. 4) 4) Código e descrição dos produtos devem ser informados. Ex.: 203 Cadastrar Se houver o mesmo produto citado mais de uma vez no texto, informe apenas o código do produto. Ex.: 203; Neste caso, não é necessária sua descrição. 5) 5) Pequenas ilustrações/imagens podem ser utilizadas de acordo com a necessidade. 6) Caso existam anexos, eles devem ser visíveis e complementares, e não podem duplicar o conteúdo do documento. 7) As abreviaturas e siglas devem vir acompanhadas de seu significado (entre parênteses). Ex.: NCM (Nomenclatura Comum do MERCOSUL). Evite redundâncias: se em um parágrafo anterior (próximo) o significado da abreviatura já foi informado, não é necessário informá-lo novamente. 8) Deve-se usar sempre o corretor ortográfico e alinhamento do parágrafo ajustado. 9) A posição de campo, botões em texto não devem ser informadas. Ex.: o botão cancelar encontra-se abaixo da tela principal. 10) Evite o uso da palavra usuário. O seu uso em demasiado empobrece o documento. 11) Verbos e preposições devem ser evitados no início de um parágrafo. Ex Exemplo 1: Para melhor

5 acompanhamento do histórico é necessário que... Página 5 de 15 Exemplo 2: Poderá ser inserido o código de barras gerado pela balança na aba "Digitar Bônus"... 12) Descrever o item na ordem em que se encontrar no fluxo. Na tela inicial, botão Novo e não no Botão Novo, na tela inicial. ATENÇÃO: É essencial o entendimento do conteúdo para que a informação seja estruturada de forma correta. 2. BOLETIM DE EVOLUÇÃO O conteúdo do Boletim de Evolução deve ser de caráter informativo, sendo objetivo, breve e direto. Em Boletim, não é comum informar os fluxos de processos e devem ser evitados, ou seja, o como utilizar (passo-a-passo) deve estar contido apenas em Tutoriais, Ajuda do Sistema. Também não devem ser transcritos conteúdo de layouts de configuração ou qualquer outro conteúdo que não seja gerado pela PC Sistemas. Neste caso, utilize apenas a referência do layout e/ou link (s), para que o usuário se informe e se precisar, busque esse tipo de documento na empresa portadora do mesmo. O Boletim de Evolução deve ser desenvolvido a partir da composição dos itens abaixo e conforme seu respectivo exemplo: CONTEÚDO NECESSÁRIO EXEMPLO Deve ser focado no contexto da alteração e Gravação de dados dos arquivos gerados chamar a atenção do leitor de acordo com o Título assunto. *Não deve inserir marcadores em títulos e deve ser evitado que o título tenha o mesmo nome da funcionalidade criada/alterada. Alteração realizada. A data, hora e identificação do usuário responsável pela geração dos arquivos O que foi feito magnéticos (CNAB 240 e 400) de remessa serão gravados durante o envio de títulos de abatimento e prorrogação. Onde foi feito Ambiente que foi criado/alterado, sendo o Ponto de Alteração (PA). Se um ou mais PA for extenso, ou seja, se 1501 Gerar Arq. Magnético Remessa CNAB 400: na tela inicial, ao clicar no botão Arquivos Gerados; somente as rotinas/funcionalidades/itens ultrapassarem mais de 03 linhas do conteúdo 1505 Gerar Arq. Magnético Remessa

6 Para que foi feito Pré-requisito ou se a sua leitura se tornar pesada e cansativa ao usuário, é importante utilizar um toogle em link para que a leitura se torne opcional. Sendo assim, a informação existirá, por ser obrigatória, mas é o usuário quem escolhe ler a informação. Motivo e benefício(s) da alteração. Condição necessária para o usuário utilizar a alteração. * Recomenda-se utilizar toogle em link para tornar a leitura opcional ao usuário quando a informação núcleo/principal (O que foi feito, onde foi feito, para que foi feito) já estiver extensa. Página 6 de 15 CNAB 240: na aba XZ, ao clicar no botão Arquivos Gerados; 1510 Remessa de Títulos: Abatimento e Prorrogação: no botão Arquivos Gerados Gerar Arq. Magnético Remessa CNAB 240: no botão Arquivos Gerados; 1510 Remessa de Títulos: Abatimento e Prorrogação: no botão Arquivos Gerados. Para melhor acompanhamento do histórico de arquivos gerados. Para que a gravação dos dados gerados no arquivo seja feita é necessário atualizar a sua tabela na rotina 560 Atualizar Banco de Dados a partir da versão 17.03, selecionando a aba Criação/Alteração de Tabelas e sub-aba L, sub-aba La-Le, opções Tabela de Cobrança Magnética. Exemplo no Boletim de Evolução: Gravação de dados dos arquivos gerados A data, hora e identificação do usuário responsável pela geração dos arquivos magnéticos (CNAB 240 e 400) de remessa serão gravados durante o envio de títulos de abatimento e prorrogação, para melhor acompanhamento do histórico nas rotinas: Modelo de toogle para ocultar informações sobre o PA (caixa de rotinas abaixo) Gerar Arq. Magnético Remessa CNAB 400: na tela inicial, botão Arquivos Gerados; 1505 Gerar Arq. Magnético Remessa CNAB 240: na aba XZ, botão Arquivos Gerados; 1510 Remessa de Títulos: Abatimento e Prorrogação: no botão Arquivos Gerados Gerar Arq. Magnético Remessa CNAB 240: na tela Arquivo Magnético, no botão Arquivos Gerados; 1510 Remessa de Títulos: Abatimento e Prorrogação: no botão Arquivos Gerados. Pré-requisito: Para que a gravação dos dados gerados no arquivo seja feita é necessário atualizar a sua tabela na rotina 560 Atualizar Banco de Dados a partir da versão 17.03, selecionando a aba Criação/Alteração de Tabelas e sub-aba L, sub-aba La-Le, opções Tabela de Cobrança Magnética.

7 Página 7 de 15 O exemplo acima é meramente instrutivo, ou seja, nem sempre o conteúdo obedecerá à ordem O que foi feito Onde foi feito Pra quê foi feito. Somente o pré-requisito deve ficar ao final do conteúdo (no caso de Boletim). O desenvolvimento do texto deve seguir a coesão, coerência, criatividade e objetividade do escritor do texto, lembrando-se sempre qual é a mensagem a ser passada e o seu tipo de público. Evite começar as frases do parágrafo inicial com Preposições e Verbos - Isso empobrece o texto. - Exemplo 1: Não ficou evidente a alteração realizada. Da forma que está escrito, é como se fosse continuação de algum assunto e não o assunto principal. Relatório com Resultado Resumido Para melhor análise do Relatório emitido, o resultado resumido referente ao número e porcentagem de clientes por motivo de não compra é apresentado com o título Resumo de Motivo de não Compra, ao preencher os campos e acionar o botão Emitir. - Exemplo 2: Não ficou evidente a alteração realizada. Da forma que está escrito, é como se fosse continuação de algum assunto e não o assunto principal. Leitura do código de barras Poderá ser inserido o código de barras gerado pela balança na aba Digitar Bônus, no campo Código de Barras e a rotina identificará automaticamente a quantidade e o código do produto. Para realizar essa verificação é necessário marcar como Sim o parâmetro Utilizar código de barras gerador por balanças no checkout da rotina 132 Parâmetros da Presidência. O exemplo abaixo deve ser utilizado para apresentar uma Nova Rotina do Sistema: CONTEÚDO NECESSÁRIO EXEMPLO O que foi feito? Alteração realizada O agrupamento de produtos poderá ser realizado na nova rotina 2073 Cadastrar Kit Benefício(s) O que o cliente ganha com a alteração realizada. Proporcionar maior agilidade nas vendas e os kit s poderão ser montados sem a necessidade de passarem pelo processo de produção de kit e, à medida que a venda for efetuada, o estoque dos produtos que compõem o kit será baixado automaticamente.

8 Principais Processos Citar o nome dos principais processos da rotina Página 8 de 15 - Cadastro de novas embalagens agrupadas - Lançamento de preço fixo para as embalagens agrupadas - Consulta de embalagens agrupadas - Replicação de embalagens agrupadas para outras filiais O Boletim deve ser documentado no Template para Boletim de Evolução. Outros exemplos, além do informado acima, poderão ser consultados no Boletim de Evolução da versão 18. Quando a alteração possuir um Tutorial/Ajuda, reduza informações que já possam estar contidas em tutorial ou ajuda e faça referência a eles da seguinte forma: Acesse o Tutorial <Nome do Tutorial> e saiba mais ou Acesse a ajuda da rotina<nome da rotina> e saiba mais. 3. TUTORIAL O conteúdo do Tutorial deve ser de caráter explicativo e orientado, com informações detalhadas, claras, de fácil entendimento e com procedimentos que facilitem a execução do processo. Imagens são utilizadas para facilitar o entendimento dos passos mais complexos quando, apenas os procedimentos ou itens descritos no texto não são de fácil compreensão. Elas tornam o texto mais atrativo, didático e explicativo. Entretanto, para não poluir esteticamente o tutorial e nem tornar a leitura extensa e cansativa não é necessário utilizar imagens em todos os passos, somente nos de difícil entendimento. O conteúdo do tutorial deve estar disposto conforme o exemplo abaixo: CONTEÚDO NECESSÁRIO EXEMPLO Título Deve ser focado no contexto do assunto e chamar a atenção do leitor. O título do assunto deve ser seguido da palavra TUTORIAL. TUTORIAL NOVOS CADASTROS Sumário Tópicos dos procedimentos. Inserir Sumário somente quando o tutorial possuir várias ETAPAS. Do contrário, não utilizá-lo. Neste caso, no Sumário devem ficar evidenciados somente Apresentação e Nome das etapas do tutorial para evitar que o usuário siga um procedimento que dependa

9 Ultimas Alterações Deve apresentar um texto explicativo e posterior tabela com as informações da criação e alterações realizadas no documento: data, versão do documento e comentários. Conforme template do tutorial. Página 9 de 15 obrigatoriamente de outro procedimento. Inserir o texto explicativo seguinte, antes da tabela, conforme template do tutorial: Abaixo, descrição da criação e das últimas alterações efetuadas no documento especificando, a data, a versão e o comentário da alteração realizada. Apresentação Deve apresentar de forma resumida a estória do processo descrito. Em seguida, deve ser feita uma breve descrição sobre o tutorial, que pode iniciar da seguinte forma: Este tutorial descreve os procedimentos necessários para <informar o objetivo do assunto>. Tópicos Deve apresentar os procedimentos relacionados ao assunto, usando imagens, de acordo com seus critérios (acima informados). Em Tutoriais também é necessário informar procedimentos que antecedem a execução dos passos, tais como rotinas necessárias e/ou passo(s) obrigatório(s) para que consiga As rotinas 202 Cadastrar Fornecedor, 203 Cadastrar e 302 Cadastrar Clientes foram aperfeiçoadas para tornar ainda mais prático os seus cadastros, onde o usuário poderá incluir novos registros, realizar suas manutenções e configurar suas informações de forma personalizada, ganhando mais tempo e praticidade durante a execução do seu processo. Este tutorial descreve os procedimentos necessários para cadastrar fornecedores, produtos e clientes utilizando o novo cadastro, com base no exemplo da rotina 203. Procedimentos Iniciais Apresentação geral do novo cadastro

10 realizar procedimentos com sucesso. *Somente inserir o tópico para Procedimentos Iniciais se este ultrapassar mais de 02 rotinas diferentes a serem informadas antes dos passos do processo. Se for inferior a este número, pode citar esses procedimentos no início dos passos do processo. * Usar o título do processo no Infinitivo (mesmo padrão dos processos (ações) da Ajuda). Ex.: Cadastrar produto; Digitar pedido de compra. * O foco do passo-a-passo é para o que o usuário fará no item e não para explicação do item (recurso, funcionalidade). Caso haja alguma informação adicional e relevante para o passo, é comum o uso de informações complementares. Página 10 de 15 O Tutorial deve ser documentado no Template para Tutorial, publicado no modo.pdf e salvo com a descrição do seu título. Exemplos (versão 18) mais completos do que o demonstrado acima, encontram-se disponíveis na pasta para tutoriais no SVN. 4. VÍDEO TUTORIAL O conteúdo do Vídeo Tutorial deve ser de caráter explicativo e orientado, com informações detalhadas, claras, de fácil entendimento e com demonstração da execução do processo. A linguagem utilizada no Vídeo Tutorial deve ser simples e objetiva, evitando os vícios de linguagem. Antes da gravação do vídeo, deve ser criado um roteiro para orientação da sequencia das ações do processo. Exemplos de roteiros encontram-se disponíveis na pasta para Vídeo Tutoriais no SVN.

11 Página 11 de AJUDA O conteúdo da Ajuda tem como objetivo instruir o usuário a utilizar todos os processos da rotina e quando existente(s), indicar o(s) processo(s) anterior (es) e/ou posterior(es). Imagens são utilizadas para facilitar o entendimento dos passos mais complexos quando, apenas os procedimentos ou itens descritos no texto não são de fácil compreensão. Elas tornam o texto mais atrativo, didático e explicativo. Entretanto, para não poluir esteticamente o tutorial e nem tornar a leitura extensa e cansativa não é necessário utilizar imagens em todos os passos, somente nos de difícil entendimento. A Ajuda está dividida nos seguintes tópicos com seus respectivos exemplos: +Tópico Principal -Subtópico +Subtópico base para todos os processos Título Apresentação da Rotina Quadro para Procedimentos Iniciais CONTEÚDO NECESSÁRIO indicador os Links com o título do conteúdo da Ajuda Como... Indicador procedimentos atualização rotinas para de de Termo pai de todos os processos Composto pelo Código Descrição da rotina Deve apresentar de forma resumida a estória da rotina descrita e os processos que serão informados no decorrer da Ajuda. Caso existam procedimentos que antecedam o processo que será descrito, informá-los antes de realizar os processos da rotina. Informar nas tabelas, os procedimentos iniciais para realizar todos os processos da rotina (Processo anterior (rotinas atualizadas), Cadastros e Parâmetros). O(s) procedimento(s) que for (em) somente para um determinado processo, não deverá (ão) ser informado(s) neste tópico. Incluir o texto indicando que, se houver necessidade de realizar atualizações de rotinas, cadastros, parametrizações e/ou o usuário possua alguma restrição/permissão de acesso na rotina, ele deverá procurar o administrador responsável pelo Sistema WinThor em sua empresa. Utilizar esse tópico apenas se a primeira palavra do título do processo for igual para todos os processos. Neste caso, a palavra deverá ser escrita uma única vez e todos os seus processos interligados deverão iniciar a partir da palavra que não se repetir em todos os processos.

12 Apresentação Quadro indicador de procedimentos iniciais Processo Exemplo: Registrar Pedido de Compra Normal Registrar Pedido de Compra Bonificada O termo pai é: Registrar Pedido de Compra... Os seus subtópicos + serão: Normal Bonificada Página 12 de 15 Fazer uma breve apresentação do processo em evidência. Alertar o usuário sobre os cadastros e parametrizações iniciais. Se houver mais algum tipo de parâmetro que seja pertinente apenas ao processo em evidência, ele também deve ser informado. Informar os procedimentos para a realização do processo. Durante o detalhamento dos procedimentos, os itens da rotina serão informados. Os itens que não são intuitivos, mas são relevantes ao usuário, devem ser explicados. Processo(s) *Se durante algum passo do procedimento for identificado o processo de outra rotina, como a abertura de uma tela por exemplo, informe resumidamente o que deve ser feito nesta outra rotina, ou se a rotina apresentada possuir Ajuda, faça apenas um link. Descrever o passo-a-passo na mesma ordem de um fluxo. Correto: Na tela inicial, clique no botão Novo; Incorreto: Clique no botão Novo, na tela inicial. Veja também Próximo processo Informação adicional ao objetivo da Ajuda Toogle de link Capacitação Continuada Faça uma breve apresentação do próximo processo ligado à outra rotina. Inserir informações que não sejam itens de passo-a-passo e/ou que não façam parte do processo. Geralmente utilizado para informar sobre cálculos e para fazer link com alguma dúvida da base de conhecimento. Inserir a seguinte informação no link Capacitação Continuada: A PC Sistemas disponibiliza soluções em treinamento, através de modalidades de ensino que vão ao encontro da necessidade específica do cliente, buscando satisfazer seu objetivo na relação de investimento x benefício. São oferecidos cursos presenciais e à distância. Os treinamentos presenciais podem ser ministrados em todos os Centros de Treinamentos da PC ou na empresa do cliente (In Loco). Conheça nossos programas de capacitação continuada, acessando o site: A Ajuda do Sistema deve ser documentada no Template para Ajuda.

13 Página 13 de REVISTA DA NOVA VERSÃO O conteúdo da Revista da Nova Versão tem como objetivo informar ao Administrador responsável pelo Sistema WinThor na sua empresa, sobre as principais novidades da versão e os procedimentos necessários para que a atualização do sistema ocorra com maior segurança e sem impactos. Quando for importante destacar alguma informação e/ou conteúdo, este poderá ser incluído como conteúdo de destaque no Revista da Nova Versão. As novidades da versão devem apresentar, de forma resumida e vendável, as seguintes informações: CONTEÚDO NECESSÁRIO EXEMPLO Título Novidade Alteração realizada O agrupamento de produtos poderá ser realizado na nova rotina 2073 Cadastro de Agrupamento de s, Benefício(s) O que o cliente ganha com a alteração realizada. Proporcionar maior agilidade nas vendas e os kits poderão ser montados sem a necessidade de passarem pelo processo de produção de kit e, à medida que a venda for efetuada, o estoque dos produtos que compõem o kit será baixado automaticamente. Veja o exemplo do Guia de Atualização da Versão anterior para melhor entendimento de todo o conteúdo. 7. CONFIGURAÇÕES ESSENCIAIS A configuração dos atributos deve ser inserida nos documentos Tutorial, Ajuda e Boletim de Evolução de acordo com o padrão de cada um destes documentos: Documento Atributo Orientação Tutorial, Ajuda e Boletim de Todos os direitos reservados. - PC Usar na criação do documento. Evolução Sistemas. Tutorial Data Data da Criação ou última modificação do documento. Tutorial Versão (do documento) Versão é uma melhoria da

14 Página 14 de 15 versão anterior, sendo que o original é o menos evoluído. Deve ser inserida na criação e última modificação do documento. 8. REFERÊNCIAS Documentação de Usuário 2011, Hypervisual - Rubem Pechansky Didática Geral, Claudino Pilleti, 2004 pesquisado em 04 de maio de 2012 no site: Boletim Pesquisas do dia 28 de março de 2012 em: Tutorial Pesquisas do dia 10 de abril de 2012 em: Ajuda (Help) Pesquisas do dia 17 de abril de 2012 em: Sistemas de ajuda da Microsoft: Word e Bloco de Notas / / Ajuda do Word Versionamento de documentos e Sistemas de informação Pesquisas do dia 24 de abril de 2012 em: MANUTENÇÃO DE DOCUMENTOS: Dissertação de mestrado em Gestão do Conhecimento e Tecnologia da Informação Universidade Católica de Brasília- DF /

15 Página 15 de 15