Padrão SuperSoft de Documentação

Neste livro estão contidas as diretrizes para a padronização da documentação dos processos (tanto internos, quanto de sistemas) da SuperSoft.

Documentação de Processos

O que é um processo?

Um processo pode ser definido como:

Sequência contínua de fatos ou operações que apresentam certa unidade ou que se reproduzem com certa regularidade; andamento, desenvolvimento, marcha.

Isso quer dizer que um processo é uma atividade com intuito de transformar uma entrada em saída. (Transformar um código fonte em executável, um documento em branco em um roteiro de testes, um clique em um relatório). Então, ao identificar uma sequência lógica de etapas que buscam completar um objetivo, isso é equivalente à dizer que estas etapas compõem um processo.

Qual é a importância da documentação de processos?

Processos bem documentados são processos bem definidos. Processos bem definidos são claros e coerentes em seus objetivos. O resultado disso é que é possível obter uniformidade na execução dos processos (sejam eles internos ou de sistemas), a partir daí, pode-se realizar o acompanhamento de forma mais apurada e coesa, já que os parâmetros para a execução dos processos estão claros e definidos. 

Uma situação muito comum, é quando um colaborador sai de férias e outra pessoa fica responsável por executar as suas atividades nesse período. Se não há uma documentação referente aos processos executados pelo colaborador que está de férias, é muito provável que a pessoa que o está substituindo encontrará inúmeras dificuldades e dúvidas em relação às decisões que devem ser tomadas, gerando frustração, perda de desempenho e/ou até erros durante os processos.

Como realizar uma boa documentação de processos?

Para realizar uma boa documentação de processos, é necessário que alguns tópicos sejam considerados e respeitados.

Sobre o armazenamento

Para o armazenamento dos documentos, centralizaremos a documentação na Wiki, sendo que, a ferramenta permite a exportação de páginas em formato html, pdf ou txt. 
Dessa forma, deve-se considerar a wiki como fonte primária de informações. Qualquer arquivo exportado, em qualquer formato, deve ser considerado como fonte secundária de informações, sendo que, por não se tratar da fonte primária, o seu nível de confiabilidade é menor por existir a possibilidade de estar desatualizado em relação ao documento original.

Sobre a definição de processos

A definição de um processo é feita a partir da formalização do processo com um documento, indicando o que é o processo, qual é o seu objetivo, onde estão os seus delimitadores (onde inicia e onde termina), quem são os envolvidos e quais informações estão relacionadas à ele. 

Sobre os roteiros de processos

O roteiro de um processo consiste na descrição de todas as etapas presentes entre o delimitador inicial e o delimitador final do processo definido. Neste documento, geralmente mais detalhado, todos os "subprocessos" que compõem o processo principal são descritos sequencialmente de acordo com a lógica do processo, sendo que, caso seja necessário/conveniente, um subprocesso pode ser um processo definido em outro documento e apenas referenciado com links quando for necessário realizá-lo.

Este documento pode ser utilizado para identificar gargalos e pontos de melhoria no processo definido.

Sobre os exemplos de processos

Um exemplo de processo, nada mais é do que uma instância de um processo, um caso de uso do roteiro documentado. Onde é utilizada uma situação real ou fictícia, indicando suas possíveis complicações/variações para ilustrar a aplicação do roteiro em cada situação possível. Diferente de um roteiro ou definição, podem existir vários exemplos de um processo visando cobrir todas possibilidades encontradas durante a realização do mesmo.

Quanto mais exemplos com situações/resultados diferentes, melhor.

Sobre informações adicionais dos processos

Para muitos processos pode ocorrer de existirem informações adicionais que são relevantes para o processo mas que não fazem parte da definição ou do roteiro do processo propriamente, algumas ocorrências desse tipo de situação são dicas de atalho, configurações recomendadas, links para consulta, etc. Para essas situações, podem ser criados documentos complementares de acordo com a demanda de cada processo.

 

 

 

Definindo escopo do documento

Considerações Inicias

A definição do escopo do documento é feita através dos seguintes fatores:

Livro/capítulo que ele está localizado

Ao iniciarmos o processo de documentação, devemos levar em consideração o livro ou capítulo em que o documento estará localizado, de maneira que a página após criada faça sentido no contexto inserido. As estruturas de livros e capítulos devem seguir uma "história", de modo que as etapas iniciais do processo estejam posicionadas antes da etapa principal ou finalização do processo.

Por exemplo, ao adicionar um documento falando sobre um pré-requisito de algum processo, é interessante que este documento seja ordenado de modo que seja a primeira página do livro ou capítulo que está contido. E caso o documento esteja definido como "pré-requisito", não é interessante que sejam documentadas etapas do processo principal nesta página, mas sim, apenas as etapas que estão antes do processo descrito no livro/capítulo.

Em uma situação onde o documento em questão é uma definição de processo, a página deve conter os itens abordados no processo, suas respectivas explicações e como o processo deve se comportar, informando o que cada etapa significa, o que deve ser levado em consideração, o motivo de tal etapa, etc. Essas definições devem ser claras e precisas, para que sirva de base para a construção de outros documentos à partir daquele. Como por exemplo, a construção de exemplos ou guias sobre o processo definido.

Outro exemplo, é um documento do tipo roteiro/guia/passo-a-passo de como realizar algum processo. Neste tipo de documento, não é interessante que estejam definições, ou explicações de como o processo deve funcionar. Em documentos desse tipo, devem ser detalhadas as etapas do processo e as questões pertinentes à cada passo, documentando desde a etapa inicial ou pré-requisito (caso exista), até a conclusão do processo.

Título da página

Em qualquer página adicionada, é importante que o título seja fiel ao conteúdo descrito no documento. Isso faz com que a biblioteca tenha um bom nível de confiabilidade, fazendo com que, quando outro usuário buscar por alguma informação, os títulos das páginas possam ser um bom filtro para identificar onde localizar a informação desejada.

Não é interessante que em uma página onde o título é "Instalação da ferramenta X", estejam descritas informações de como utilizar a ferramenta ou o motivo de utilizar tal ferramenta.

No caso acima citado, seria interessante possuir um capítulo contendo duas ou três páginas para o conteúdo, dividindo da seguinte maneira:
Capítulo: Ferramenta X
Páginas: Apresentação da ferramenta; Instalação e Configuração; Dicas e atalhos;

Público alvo

Na criação de documentos, outro tópico de extrema relevância é o público à que o documento está destinado. Por se tratar de uma plataforma onde diversos setores possuem acesso, e dentro desses setores podem existir desde pessoas que não conhecem o processo documentado à pessoas que dominam completamente o mesmo processo. Deve-se levar em consideração que todos, à partir do processo documentado, consigam entender ou pelo menos assimilar do que se trata.

Entre os objetivos da documentação, um deles é a possibilidade de iniciar novos colaboradores aos processos (sejam internos ou do sistema), para que formem um entendimento das rotinas e de como elas devem funcionar. Por isso, ao criar um documento, não poupe detalhes. 

Ao avançar na documentação, caso observe que o conteúdo está muito denso (ou seja, possui um nível de detalhamento excessivamente alto). Verifique a possibilidade de dividir o documento em duas ou mais páginas para que fique mais fácil a "digestão" das informações pelas pessoas que consultarão o documento posteriormente. Podendo criar uma página com informações mais básicas do processo e outra com uma visão mais ampla e generalizada.

Para isso, utilize de callouts informativas com descrições do tipo "Caso você não saiba como realizar tal ação, clique aqui" ou "Para maiores informações sobre determinada etapa, consulte tal página"

Padrões de formatação

Pré-requisitos:

Antes de começar a conhecer os padrões dos documentos inseridos na plataforma, é necessário que tenha visto o livro que orienta na criação dos livros, capítulos e páginas. Para acessar o livro clique aqui.

Títulos, Subtítulos e Listas

A adição de títulos tornam a plataforma mais organizada e de fácil visualização para todos, então a seguir será demonstrado como e quando utilizar cada tipo de cabeçalho disponível afim de tornar a plataforma mais agradável e compreensível possível. 

Títulos e Subtítulos 

Possuímos 4 maneiras de deixarmos nossos títulos destacados. As diferenças entre eles são: o tamanho e a forma na qual a plataforma organiza os subtítulos dentro dos títulos, seguindo um nível hierárquico.

image-1614086038638.png

Exemplo do modo que a plataforma organiza em relação à utilização dos diferentes tipos de títulos.

  1. Header Large deve ser utilizado para o título geral da página, o título no qual todos os subtítulos e tópicos da página estejam diretamente ligado à ele;
  2. Header Medium somente deve ser utilizado, quando o assunto tratado por ele conter subtítulos e esses subtítulos tenham outros subtítulos dentro deles;
  3. Header Small constantemente será utilizado para adicionar um conteúdo que contenha seus subtítulos, mas que não tenha mais nenhum outro subtítulo dentro dos subtítulo do "Header Small";
  4. Header Tiny são utilizado para os subtítulos das páginas, pois ficam organizados com um nível de indentação em relação à seus títulos.

De maneira geral, ao iniciar a escrita de um documento, inicie adicionando pelo ultimo tipo de título, no caso o menor (Header Tiny), e conforme avançar no processo de documentação, caso se depare com um tópico que contenha subtópicos que merecem ser destacados na hierarquia do documento, altere os tópicos principais que anteriormente estavam formatados como Header Tiny para um nível acima (Header Small) e formate os subtópicos recém-adicionados como Header Tiny. 

Caso ocorra de dentro de um subtópico, ser necessário necessário criar mais um nível de subtópicos, então repita o processo "promovendo" os títulos já existentes e adicionando os novos com a menor formatação possível.

Listas

As listas numeradas e lista de marcadores devem ser utilizadas ao adicionar conteúdo nos quais devem seguir uma ordem ou cujo os temas são relacionados e precisem ser agrupados. 

Listas também devem ser utilizadas para descrever pré-requisitos de um processo ou etapa.

Callouts 

Existem 3 maneiras de utilizar os callouts (podendo variar dependendo da situação):

Os callouts de "Success" e "Danger" são excelentes para demonstrar como se deve fazer ou não algum processo, um bom exemplo da utilização deles é a página de espaçamento.

O callout de "Info" destaca um informação na qual é considerada importante na página ou tema inserido.

O callout de "Warning" deve-se utilizar para informar atenção sobre um determinado assunto.

Links 

Ao adicionar um conteúdo que tenha ligação direta à outro tema já existente na plataforma, deve-se utilizar o link para referenciar a outra página de maneira que quem esteja lendo, caso queira conhecer esta outra página, basta clicar em alguma palavra ou imagem que contenha o link, que será redirecionado para a mesma.

Quando você utilizar um link que irá redirecionar para outra página, deve-se selecionar a opção "New window", que irá abrir uma nova guia com o conteúdo do link adicionado, que caso você queira voltar para a página anterior, basta fechar a nova página que foi aberta ao clicar no link.

image-1613679837025.png

Além disso você deve deixar o link sublinhado, que indicará que é um link e que irá te redirecionar para outra página em uma nova guia. 

Quando adicionar um link que aponta para a mesma página, deve-se selecionar a opção de "None", que não irá abrir uma nova guia, mas sim redirecionar direto para a parte da página na qual você adicionou o link.

Caso o link que você for adicionar seja na mesma página e ele seja um título ou subtítulo de algum tópico, você consegue selecionar ele pela aba de adição do link, conforme será mostrado a seguir: 

image-1613734367967.png

Como visto acima, ao clicar na caixa de Url, a própria Wiki, irá apresentar todos os títulos e subtítulos da página, e selecionando o desejado e salvando, ao clicar na palavra na qual você adicionou o link, será redirecionado direto para aquela parte da página.

Notações

Existem diversas notações que podemos utilizar para facilitar o entendimento do conteúdo e também organizar melhor os conteúdos a serem adicionados. A seguir será demonstrado algumas notações e como utiliza-las ao adicionar uma nova informação à plataforma.

Palavras Estrangeiras

Algumas vezes será necessário utilizar palavras estrangeiras, então elas devem ser adicionadas como Italic, que faz uma leve inclinação para a direita na palavra, fazendo com que seja mais fácil identificar que se trata de uma palavra estrangeira.

Tabelas

Ao adicionar uma tabela, seu conteúdo deve ser alinhado ao centro, a largura das colunas devem ser ajustadas conforme a maior coluna (título ou conteúdo) e os títulos devem ser colocados em negrito, caso existam. Por exemplo, as tabelas a seguir:

Responsável Data Prevista Data de Entrega
Fulano da Silva 10/02/2021 25/02/2021
Irineu da Fonseca  15/03/2021 25/05/2021

A tabela acima está sem nenhuma formatação padrão, ao formata-la no padrão pré-estabelecido ela deve ficar parecida com a seguinte tabela:

Responsável Data Prevista Data de Entrega
Fulano da Silva 10/02/2021 25/02/2021
Irineu da Fonseca  15/03/2021 25/05/2021

 

Imagens

Ao adicionar uma imagem à plataforma ou uma legenda para a mesma, você deve alinhar centralizado através do botão "Allign center". Assim como o conteúdo de tabelas também devem ser centralizados.

Formatação do texto 

A formatação vai depender muito do que estiver sendo adicionado, mas por padrão deve-se seguir algumas maneiras para tornar plataforma mais organizada e padronizada.

A cor padrão é preto, salvo exceções bem especificas e que sejam realmente necessário. 

Negrito

Negrito deve ser sempre utilizado para destacar alguma palavra chave ou de extrema importância, de forma que ao ler apenas os termos em negrito, seja possível entender aquele trecho.

Além disso, negrito também é utilizado nos títulos e subtítulos das páginas.

Outro uso para a formatação em negrito é para um link que aponte para a mesma página.

Itálico   

O Itálico deve ser utilizado ao adicionar uma palavra estrangeira, que será uma maneira de fácil identificação que a palavra não é oriunda da nossa língua nativa. Que é um método bastante utilizado nos sites de pesquisas.   

Sublinhado 

O Sublinhado está sendo destinado a links que direcionam a para uma nova página, que deve ser aberta em uma nova guia.

Sobrescrito

O uso de sobrescrito está restrito para a adição de referências. Onde deve-se utilizar um valor numérico após a palavra ou frase que será referenciada no final da página.

Subscrito

O uso de subscrito está restrito para descrições de imagens. Ao adicionar uma imagem, logo em seguida, utilize o subscrito de forma centralizada para identificar a imagem.

Alinhamento Padrão

O alinhamento padrão utilizado é sempre à esquerda, que por padrão a Wiki já configura quando inicia a inserção de algum conteúdo novo.

Linha Horizontal

Sempre que uma página possuir algum tipo de pré-requisito, seja por ser continuação de outra página ou por outro conhecimento necessário antes de avançar na leitura do documento, deve-se utilizar uma linha horizontal demarcando o pré-requisito, do início do conteúdo abordado na página. 

Além disso, as linhas horizontais devem ser utilizadas para separar tópicos diferentes dentro da mesma página. Indicando o fim do tópico abordado e início do tópico seguinte.

Fluxogramas 

Ao adicionar um fluxograma na Wiki, caso o mesmo não seja tão grande, adicione diretamente o fluxograma, mas se for um fluxograma grande, que ficará difícil visualizar os textos contidos nele, adicione uma imagem e crie um link nela que direcione para outra página, pois nesta nova página será muito mais fácil de ser visualizada. 

Mensagens de Versionamento

As mensagens de versionamento devem conter o relato das alterações ou adições de conteúdos, sejam pequenas alterações ou criações de novas páginas, pois caso surja a necessidade de retornar alguma página à alguma versão anterior, seja mais fácil de identificar através das mensagens de versionamento.

 

Tipos de Documentos

Tipos de Documentos

Estrutura de definição dos processos

Antes de iniciar a documentação de um processo, verifique se o mesmo já não está documentado, pois caso esteja, ao invés de criar um documento duplicado, pode-se analisar e complementar a documentação do processo tornando-a mais completa e confiável.   

Uma definição de processo deve conter:

Nome do processo 

Inicialmente você deve utilizar ou criar um nome descritivo do que o processo em geral irá fazer, que tenha relação direta com o resultado final esperado. 

Este nome será o nome utilizado no capítulo responsável pela documentação do processo em questão.

Processos devem possuir responsabilidades únicas, ou seja, evite criar processos do tipo "Executar processo e verificar valor" ou "Gerar relatório e enviar e-mail"

Resumo do processo

No resumo do processo, deve-se realizar uma descrição do que é o processo documentado, contextualizando a sua descrição à rotina que ele pertence (caso exista).

Envolvidos no processo

Todo processo tem pessoas, sistemas ou departamentos envolvidos, relatar quem são esses envolvidos ajuda para definir quem são os "responsáveis" diretamente naquele determinado processo.

Etapas do processo

Neste tópico, deve-se "quebrar" o processo em etapas, informando de maneira sucinta o que irá acontecer durante a execução do processo. 

Ponto inicial do processo

Todo processo possui uma origem, então é importante analisar e descrever quem ou o que é o "gatilho" responsável pelo início da execução do processo documentado. Esse "gatilho" pode ser um clique, a conclusão de um processo anterior, um evento, etc.

Ponto final do processo

O ponto final do processo é a ultima ação cujo seu processo irá executar, para identificar este ponto é importante responder a seguinte pergunta: Após qual etapa, o processo pode ser considerado como concluído?

Resultado esperado

Todo processo tem um resultado, que se forem respeitadas todas as etapas, apresentará um resultado que era esperado. Neste tópico, também é importante relatar possíveis resultados incorretos e o que pode ter gerado tal resultado. Resultados estes, que serão documentados no "roteiro do processo".

Para um exemplo de definição de processo, consulte o capítulo "Revisão Colaborativa". [linkar após conclusão da refatoração do processo]

Tipos de Documentos

Roteiro de Etapas do Processo

O roteiro de etapas de um processo nada mais é do que a descrição detalhada de cada uma das etapas que deverão ser seguidas para sua conclusão.

O roteiro de etapas do processo deverá estar dentro de um capítulo responsável pela documentação do processo em questão e abaixo de sua definição.

Um roteiro de etapas do processo deve conter:

Nome da etapa do processo que será feito o roteiro

O nome da etapa do processo deve ser condizente com alguma das etapas do processo já descritas na estrutura de definição do processo. Assim qualquer usuário ao ler o nome/título da página saberá que a mesma é referente à uma etapa específica do processo.

Resumo da etapa do processo

No resumo da etapa do processo, deve-se realizar uma descrição do que é especificamente essa etapa, contextualizando a sua descrição ao processo que ela pertence.

Pré-requisitos necessários para realização da etapa do processo

Enumerar todos os processos ou etapas que precisam ser realizadas antes de dar início à execução da etapa em questão, ou seja, listar quais são as condições para que a etapa possa ser executada. Dentro da definição de um processo existem diversas etapas que precisam ser realizadas, essas etapas normalmente dependem de uma sequência de execução para que possam ser realizadas. A hierarquia dessa sequência são os pré-requisitos para realização das etapas seguintes e assim por diante.

Detalhar especificamente a etapa do processo em questão

Nesse tópico devem ser detalhados todos os processos necessários para a realização da etapa em questão, com o máximo de detalhes possíveis, imagens, instruções e dicas que auxiliem na execução da mesma. Obrigatoriamente uma etapa tem um ponto de início, ou seja, a partir de que momento essa etapa deve ser realizada e um ponto final, que indica quando a etapa pode ser considerada como concluída.

Resultado esperado

Toda etapa do processo tem um resultado, positivo ou negativo, onde se seguidos todos os passos citados no detalhamento da etapa, obteremos o resultado esperado.

Para um exemplo de definição de etapas de um processo, consulte o capítulo "Processo: Aguardando Revisão". [linkar após conclusão da refatoração do processo]

Tipos de Documentos

Informações Adicionais do Processo

Introdução

Arquivos desse tipo são utilizados para documentar informações adicionais de processos, que embora não façam parte da sua definição ou do seu roteiro, merecem ser mencionadas para melhor aproveitamento ou desempenho do colaborador que irá executar esse processo posteriormente.

Por se tratar de um tipo de documento que pode ter vários formatos ou objetivos, nesta página estarão descritas algumas condições para validar se as informações candidatas à documentação são realmente informações adicionais do processo e devem possuir uma página desse tipo, ou devem estar presentes em outro tipo de documento, ou até que não necessitem ser documentadas.

Validando as informações candidatas

Antes de iniciar propriamente a construção do documento, deve-se realizar as seguintes perguntas:

Caso a resposta seja "sim" para alguma das perguntas acima, então talvez essas informações não devem estar em um documento adicional, e sim em outro tipo de documento.

Caso contrário, então avançaremos na validação das informações candidatas.

Apesar da resposta dessa pergunta ser subjetiva e muito abrangente, o objetivo final de toda e qualquer documentação é: auxiliar outra pessoa, que posteriormente irá realizar o mesmo processo à avançar sobre quaisquer impasses que possam surgir durante o processo. Neste caso, podemos utilizar a metáfora dos anões sobre ombros de gigantes, onde expressa o significado "descobrir a verdade a partir das descobertas anteriores". 

Caso o objetivo de documentar as informações adicionais seja o objetivo descrito acima, então essa informação merece ser documentada, podendo assumir o formato de (Dicas sobre o processo; Atalhos; Materiais complementares; etc)

Modelos de Documentos

Modelos de Documentos

Modelo Definição

Resumo do processo
 
Envolvidos no processo
 
Etapas do processo
 
Ponto inicial do processo
 
Ponto final do processo
 
Resultado esperado

 

 

Modelos de Documentos

Modelo Roteiro

Nome da etapa

 

Resumo da etapa

 

Pré-requisitos

 

Detalhamento da execução da atividade

 

Resultado esperado