Versão 1.0 - 2016

A Consenso Tecnologia atua nas diversas áreas que compõem o setor comercial de empresas de saneamento. Seu foco são as mais modernas tecnologias e metodologias de desenvolvimento de sistemas em uso atualmente no mercado. Seu carro-chefe é a solução GSAN, um software livre, para a gestão comercial de serviços de saneamento. Chama-se software livre pelo fato de seus códigos-fonte e demais artefatos de sistema poderem ser baixados por qualquer pessoa física ou jurídica.

O Sistema Integrado de Gestão de Serviços de Saneamento (GSAN) é um sistema desenvolvido para a gestão comercial das companhias de abastecimento de água e saneamento de esgoto, garantindo uma gestão integrada e eficaz, de todas as funções desempenhadas por essas companhias. Seu desenvolvimento foi financiado pelo Projeto de Modernização do Setor Saneamento (PMSS) e pode ser implantado em qualquer companhia de abastecimento de água e saneamento de esgoto do Brasil, graças ao seu alto grau de parametrização. O GSAN utiliza interface WEB e pode ser acessado por qualquer navegador disponível no mercado. O sistema foi 100% desenvolvido com ferramentas livres e de código aberto, não sendo necessária a aquisição de nenhum software proprietário para a sua implantação.

O GSAN é dividido em sete módulos principais:

Conjunto de atividades e procedimentos que visam manter atualizados os dados que permitem o conhecimento e a abordagem dos clientes, controlando e atualizando informações para o planejamento das companhias e a comercialização dos serviços.
Palavras-chave: Dados \ Clientes.

Conjunto de atividades e procedimentos que visam à determinação do volume de água e esgoto que flui através dos hidrômetros utilizados para a medição do consumo dos imóveis.
Palavras-chave: Hidrômetro \ Medição.

Conjunto de atividades e procedimentos que visam à cobrança socialmente justa dos serviços prestados pela empresa, abrangendo tabelas de tarifas, composição dinâmica de grupos de faturamento, análise de anormalidades de leituras e consumos, refaturamentos e fiscalizações.
Palavras-chave: Valores \ Contas.

Conjunto de atividades e procedimentos que visam ao recebimento dos débitos dos clientes, abrangendo controle de documentos não entregues, identificação de clientes responsáveis pelo pagamento, definição de ações de cobrança, parcelamentos de débitos, transferências de débitos, cobrança administrativa e judicial e quitação antecipada de financiamentos.
Palavras-chave: Clientes \ Débito.

Conjunto de atividades e procedimentos que visam ao recebimento e devoluções decorrentes das atividades comerciais processadas, permitindo sua contabilização e a comparação entre os valores informados pelos arrecadadores e os valores processados.
Palavras-chave: Valores \ Entrada \ Saída.

Conjunto de atividades e procedimentos que permitem o registro, acompanhamento e controle das solicitações e reclamações, tanto do público externo quanto do interno (diversas unidades da empresa).
Palavras-chave: Serviços \ Público.

Conjuntos de atividades e procedimentos que permitem a consulta analítica das informações existentes no GSAN. Essas consultas podem ser feitas através de relatórios gerenciais utilizando a tecnologia de BI (Business Intelligence), denominada OLAP (On Line Analytical Processing), onde o relatório é visualizado de forma analítica ou sintética; ou através de uma versão com integração com o Pentaho CE, através de uma base OLAP modelada sobre o banco colunar HP Vertica.
Palavras-chave: Informações \ Clientes diferenciados.

A Consenso utiliza a plataforma Dokuwiki para redigir, editar e armazenar sua documentação de sistemas. Essa organização é direcionada para que o usuário final encontre a informação de forma rápida e simples, em uma linguagem compatível com seu grau de entendimento técnico. A plataforma permite ainda uma edição simplificada, que facilita as alterações necessárias sempre que for preciso modificar, complementar, atualizar ou corrigir os textos.

Para a documentação de suas soluções, a Consenso trabalha com dois modelos: os Casos de Uso e a Documentação de Usuário.

O que é um caso de uso?

De um modo geral, em documentação técnica, casos de uso descrevem o fluxo principal de passos que formam sequências de ações realizadas pelo sistema para produzir um resultado de valor observável pelo usuário.

O que é um fluxo principal?

É uma narrativa que conta como um sistema se comporta até atingir seu objetivo em condições ideais. Além do fluxo principal, o caso de uso pode também conter fluxos de exceção (que descrevem o caminho que o sistema toma, caso certas condições ideais não sejam atendidas) e subfluxos (que são fluxos secundários, subordinados ao fluxo principal).

Qual a função de um caso de uso?

Registrar os requisitos funcionais e auxiliar no cálculo de custos de um projeto são as principais funções do caso de uso.

Quais os passos que compõem um caso de uso?

Além dos fluxos: principal, secundários e de exceção, um caso de uso pode ser composto de: histórico de revisões, atores, diagrama de casos de uso, informações técnicas adicionais, tabelas relacionadas, referências, especificação executável e modelo de telas e modelo de relatório.

Quem documenta e a que público se dirige um caso de uso?

Os casos de usos compreendem uma linguagem mais técnica e são direcionados aos analistas e desenvolvedores. Como sua composição requer um conhecimento técnico avançado, sua redação é feita pelo analista de sistemas. Na Consenso, cabe ao documentador apenas inserir no Dokuwiki um novo caso de uso quando solicitado.

Para inserir um caso de uso, é necessário se ater à sua numeração. Os casos de uso devem ser identificados com um identificador único. A numeração inicia com o identificador [UC0001] e prossegue sendo incrementada em ordem crescente, à medida que forem surgindo novos casos de uso.

Atualmente, a Consenso conta com, aproximadamente, 1300 casos de uso documentados no Dokuwiki, divididos em módulos: Arrecadação, Atendimento ao Público, Cadastro, Cobrança, Controle de Acesso, Controle Batch, Faturamento, Financeiro, Geral, Gerencial, Integração, Loja Virtual, Micromedição, Operacional, Relatórios, Segurança e Mobile.

Esse tópico considera a hipótese de o caso de uso ter sido documentado na ferramenta de texto Word. Para inseri-lo no Dokuwiki, precisamos antes convertê-lo para HTML; em seguida, para a linguagem Dokuwiki.

No endereço http://www.textfixer.com/html/convert-word-to-html.php acessamos o conversor de Word para HTML.

Copie cole o texto no Box acima e clique em . O botão ficar no mesmo lugar que Back to Word View (que é o Convert Word to HTML antes da conversão).

Convertido para HTML? Copie e cole o texto em HTML no Conversor Wiki:

Esse programa é baixado gratuitamente e pode ficar na área de trabalho de seu computador. Assim que o texto em HTML é colado, a versão para Dokuwiki já sai do outro lado. Copie o texto e jogue no Dokuwiki para padronizá-lo e publicá-lo (conforme detalhado no capítulo Padronizando os Textos no Dokuwiki).

Como os casos de uso descrevem a maneira como um processo do sistema se comporta para produzir um resultado de valor observável pelo usuário, as alterações são bem comuns de acontecer, uma vez que o sistema é algo dinâmico, passível de receber melhorias, acréscimos e exclusões, de acordo com as necessidades identificadas durante a rotina do cliente.

É na Tabela de Histórico de Alterações que essas alterações são marcadas, tanto para mapear a mudança de um processo quanto para auxiliar o documentador, que precisará atualizar a documentação de usuário correspondente, sempre que a alteração mudar um campo, inserir um botão, ou qualquer outra melhoria que altere a maneira como a funcionalidade se comporta:

Note que as alterações são assinaladas com uma cor específica. Essa cor assinala, no texto, a sua alteração correspondente. Por uma questão de organização, devemos assinalar apenas as quatro últimas alterações, mantendo as demais na tabela, mas sem cor.

Além da Tabela de Histórico, todo caso de uso deve vir com as seguintes informações:

1. Ator: usuário responsável pelas ações do processo descrito no caso de uso (na ferramenta de edição, clique no link indicando a complexidade do ator para aprender um pouco mais sobre isso).
2. Prioridade: Prioridade do caso de uso, variando entre Essencial, Importante e Desejável.
3. Pré-condição: pré-condições necessárias para que o processo descrito pelo caso de uso se desenrole satisfatoriamente. Por exemplo: ter um parâmetro ativo, ou receber informações de uma pesquisa de filtro, etc.
4. Pós-condição: resultado final do processo descrito.
5. Complexidade: complexidade do caso de uso (na ferramenta de edição, clique no link indicando a complexidade do caso de uso para aprender um pouco mais sobre isso).

O diagrama do caso de uso visualiza todas as funcionalidades ligadas à funcionalidade principal documentada. Em outras palavras: é a visualização de todas as funcionalidades “chamadas” pela funcionalidade principal.

Na sintaxe do Dokuwiki, o diagrama é expresso com a seguinte tipografia do exemplo abaixo:

Onde, a funcionalidade marcada em amarelo é a principal, e as marcadas em azul são as subordinadas. Os termos “up”e “right”indicam a posição da funcionalidade subordinada no diagrama: “acima” e “à direita”, respectivamente, podendo ainda ser informada o termo “left” para posições “à esquerda”.

A leitura visual da sintaxe acima é a que segue:

Quando a funcionalidade não tiver nenhuma outra funcionalidade ligada, o diagrama fica conforme o exemplo:

Em sua leitura visual:

Quando mais de dez casos de uso estiverem relacionados à funcionalidade principal, sua visualização e disposição no diagrama ficam prejudicadas. Por isso, utilizamos outro modelo de diagrama:

No modelo de sintaxe da figura 6, os termos “right” e “left” indicam de que lado os casos de uso ficarão, dentro do retângulo do diagrama. Já a notação “\n” serve para dar espaço de parágrafo entre as palavras. Isso é especialmente importante para títulos de casos de uso muito extensos.

Veja abaixo a leitura visual:

Observação: note nos casos de uso UC0142 e UC0009, a função da notação “\n”.

A documentação de usuário se utiliza de uma abordagem mais didática e menos técnica, cujo objetivo é orientar o usuário comum durante a utilização das funcionalidades do sistema GSAN. Essa documentação é de responsabilidade do documentador de sistemas, não necessariamente alguém com formação técnica, mas com uma redação limpa, capaz de transformar o conhecimento técnico de determinada funcionalidade em um processo claro, que consiga tirar as dúvidas do cliente final.

Uma boa documentação de usuário diminui o impacto das demandas tanto da área de suporte quanto da área de atendimento ao público.

A documentação de usuário também é dividida em módulos: Faturamento, Batch, Atendimento ao Público, Arrecadação, Micromedição, Segurança, Cadastro, Mobilidade, Cobrança, Loja Virtual, Operacional, Gerencial, Financeiro, Relatórios.

Na ferramenta de documentação, os módulos do GSAN ficam assim disponibilizados para acesso no Menu Principal. Basta clicar sobre eles para acessar a documentação específica de usuário.

O próximo passo é aprender a padronizar o texto da documentação de usuário no Dokuwiki. Fazemos isso através daquilo que chamamos de indentação. A principal vantagem da indentação é fazer com que o usuário comum encontre com mais facilidade as informações que precisa, uma vez que costumam vir sempre ordenadas da mesma forma. Isso é válido, sobretudo, para modelos de funcionalidades complexas, com muitos campos a preencher.

Abaixo, temos um modelo de padronização:

À nossa direita, na Tabela de conteúdos, temos a visualização do que fizemos no campo do texto. Note que os tópicos são ordenados conforme prioridade:

1. Título da funcionalidade;
2. Observação;
3. Preenchimento dos campos;
4. Modelo de relatório;
5. Tela de Sucesso;
6. Funcionalidade dos botões.

Ao clicar sobre cada um deles, somos direcionados para o ponto correlato no texto documentado. Isso facilita a navegação do usuário, principalmente se o processo for longo e o usuário necessitar de uma informação específica.

Mais à direita, temos os ícones de uso do documentador:

1. Clicando em Editar Página, visualizamos o conteúdo do processo na sintaxe Dokuwiki, pronto para ser editado.
2. Em Revisões Anteriores, visualizamos a data e o horário em que determinado conteúdo do texto foi editado, bem como que usuário editou o processo.
3. Já em Links Diversos, visualizamos apenas os links existentes no processo, apontando para outros processos inseridos no Dokuwiki.
4. O ícone Monitorar alterações é restrito a usuários com permissão especial. Serve para definir quais usuários serão autorizados a editar o processo.
5. Utilizamos Rename Page para alterar o título do processo no Dokuwiki. Podemos fazer a ação diretamente no texto. A diferença é que, através de Rename Page,todos os links que porventura existam, relacionando-o a outros processos, são alterados automaticamente.
6. Ao clicar em Export to PDF, todo o processo é passado para PDF e salvo no computador, para fins de consulta, envio ou impressão.

Como dissemos antes, clicando em Editar Página, visualizamos o conteúdo do processo na linguagem Dokuwiki, pronto para ser editado.

Na barra de ferramentas superior, temos algumas funções de edição importantes:

Basta passar o cursor do mouse sobre cada ícone para que sua função seja visualizada.

Na barra inferior, temos mais algumas funções de edição importantes:

1. Editor Visual: clicando aqui, o texto sai da edição e é visualizado como o usuário o enxerga.
2. Visualizar: clicando aqui, o processo é visualizado abaixo, da maneira como o usuário o enxerga, sem fechar a tela de edição. É uma função muito importante, pois permite ao documentador comparar o que está fazendo, visualizando a maneira como suas alterações ficarão, antes de salvar a nova versão do processo.
3. Changes: clicando aqui, o documentador visualiza as diferenças entre a versão em que está trabalhando com a versão atual, antes de salvar a nova versão do processo. É uma função pouco utilizada, uma vez que através de Visualizar podemos efetuar a mesma ação de maneira mais eficiente.
4. Cancelar: clicando aqui, a edição é cancelada sem salvar.
5. Resumo da edição: esse campo é importantíssimo. É com ele que todas as alterações que forem efetuadas podem ser registradas para conferência posterior. Informando esse campo, ao clicarmos em Revisões Anteriores, visualizamos não apenas a data, o horário e o usuário responsável pela edição, mas o detalhe do que foi feito. Exemplo:

Note que assim que é preenchido, o botão Salvar é habilitado. É clicando nele que a versão do processo editado muda, aguardando validação. Até o processo ser validado, a seguinte mensagem pode ser visualizada sempre que for acessado:

Atenção: a aprovação/validação do documento final não é feita pelo documentador.

A documentação de usuário segue um padrão pautado pela Tabela de Conteúdo conforme figura 11 abaixo:

• 1. Desfazer Cancelamento ou Retificação: o primeiro tópico é o principal. Ele traz o título da própria funcionalidade, mais a descrição básica do seu funcionamento. Em seguida, é necessário apontar no texto o caminho que o usuário percorrerá no Menu do GSAN até chegar a essa funcionalidade. Abaixo, um exemplo da árvore de Menu do GSAN:

No GSAN, a árvore do Menu é dividida em módulos. Para abrir os módulos, basta clicar no sinal de “+” ao lado de cada um, até localizar a funcionalidade. Só lembrando que, dentro de um módulo, é comum haver submódulos com o sinal de “+”.

Nesse caso, o caminho até chegar a funcionalidade é o Menu GSAN > GSAN > Faturamento > Conta > Desfazer Cancelamento ou Retificação.

É no tópico principal que a tela principal da funcionalidade deve ser visualizada. Para printá-la, podemos usar qualquer editor de imagem, como o PaintBrush. Depois de printá-la, devemos salvar a imagem em nosso computador, para posterior inserção no DokuWiki.

Para inserir uma imagem no DokuWiki, clique em Editar Página (conforme tópico Editando os Textos no Dokuwiki). Em seguida, clique no ícone Adicionar imagens e/ou outros arquivos (indicado na Figura 13).

Feito isso, o sistema abre uma janela para seleção da imagem:

Clique em Escolher Arquivo e selecione a tela salva em seu computador (obrigatoriamente, a imagem precisa ser salva na extensão JPEG). Assim que a imagem for selecionada, ela aparecerá logo abaixo do campo Buscar Arquivo. No exemplo da Figura 13, temos a tela 1filtrar_motivo_revisao.jpg. Clique duas vezes sobre a tela. Feito isso, o sistema abre a janela para ajuste do link da imagem:

Clique sobre o ícone assinalado acima. É importantíssimo clicar sobre ele, para que a imagem não vá para o texto apontando para um link, mas sendo visualizada. Em seguida, clique no botão Inserir. Feito isso, o sistema insere a tela de funcionalidade que trata a documentação:

Na Figura 14 temos o modelo padrão de que modo a tela precisa ser inserida: todos os campos visíveis; acima, a descrição do caminho completo na árvore de Menu para se chegar até a funcionalidade; abaixo com a última versão do produto, seguido de data e horário.

Atenção: na sintaxe dos textos no DokuWiki (ver tópico Sintaxe dos textos no Dokuwiki) a imagem de tela inserida deve ficar com a descrição:

• 2. Observação: Como trabalhamos com informações confidenciais dos clientes, todas as telas cujos campos constem informações confidenciais (endereço, nome do cliente, telefone, etc.) devem ter essas informações apagadas ainda no editor de imagem.Além disso, toda a documentação de usuário deve vir com o lembrete da informação, a seguir:

• 3. Preenchimento dos Campos: Aqui devemos descrever o preenchimento de cada campo da funcionalidade, indicando os parâmetros necessários para que a funcionalidade atinja seus objetivos e a obrigatoriedade ou não do preenchimento dos campos.
  • Atenção: Ainda que este seja o local específico para a descrição do preenchimento dos campos, é importante detalharmos no tópico principal o comportamento que o preenchimento dos campos acarretará para a funcionalidade; os parâmetros necessários para que fiquem habilitados e sua relação com os demais campos.
  • Na funcionalidade, os campos obrigatórios são assinalados ao lado com um asterisco vermelho.
• 4. Tela de Sucesso: a tela de sucesso é uma maneira de demonstrar ao usuário final a tela que indica que o processo foi concluído com sucesso, caso os campos tenham sido preenchidos corretamente e os procedimentos tenham sido efetuados a contento:

• 5. Relatórios: Caso a funcionalidade seja uma tela de filtro cujo resultado final seja a visualização de um relatório de dados, este também deve constar na documentação. Para tanto, seu tratamento é o mesmo para a captura de uma imagem.
• 6. Funcionalidade dos botões: Fechando a documentação do usuário, temos a descrição de cada botão da funcionalidade, bem como o processo posterior que desencadeia. Caso o acionamento do botão acesse outra tela ou janela, estas deverão também estar inseridas e descritas no processo.

Como vimos no tópico do diagrama dos casos de uso, cada funcionalidade pode ter outras funcionalidades subordinadas a ela, no cumprimento de algum processo específico. Além do diagrama, essas funcionalidades devem estar assinaladas no texto em forma de links apontando para o próprio Dokuwiki. Isso é válido tanto para casos de uso quanto para a documentação do usuário.

A ideia é facilitar a navegação do usuário, apontando os caminhos que determinado processo pode tomar.

Antes de tudo, precisamos entender o padrão do endereço da documentação na barra de endereços:

Quando acessamos qualquer documentação no Dokuwiki, a barra de endereço do navegador indicará sua localização. Para efeitos de inserção de links, consideramos tudo o que está do sinal de “=” para a direita. No caso da figura 16:

=ajuda:inserir_tipo_de_credito

No Dokuwiki, coloque o texto em modo de edição. Em seguida, identifique no texto o trecho onde quer que o link interno seja visualizado. Selecione o trecho com a ajuda do mouse. Em seguida, clique no ícone do link na barra de edição:

A seguinte janela será visualizada:

No campo Link para: insira o endereço da barra, conforme especificação, e clique no seu teclado, em Enter. Feito isso, o link é inserido no texto.

Depois de salvar a versão, o trecho do link deve ficar em verde no texto. Se ficar em vermelho, significa que algo está errado com o endereço. Teste o link clicando sobre ele, confirmando se de fato ele direciona para a página correta.

Além da documentação das funcionalidades, a Consenso Tecnologia também trabalha com guias gerais de processos de negócio e com manuais. A redação de ambos também é responsabilidade do documentador.

Os guias gerais são fluxogramas que apresentam uma visão macro orientada a processos e direcionada à realidade externa do cliente. A intenção é dar uma visão geral de todas as partes que funcionam na empresa, com fins de atender às necessidades do cliente.

É uma visão funcional orientada a atividades colaborativas, mas sem a necessidade de interação de todas as partes relacionadas à atividade. Exemplo: dentro do macroprocesso de Arrecadação, desenhar apenas o fluxo do processo de arrecadação via débito automático.

E o que é um processo? É conjunto de atividades realizadas em uma sequência específica. Seu objetivo é viabilizar a produção de um bem ou serviço que agregue valor ao cliente. Além disso, um conjunto de processos de negócio representa de que modo a empresa funciona e produz seus resultados.

Para mais informações clique aqui.

Os manuais de usuário contêm as informações básicas de como se comportam processos maiores, em geral que integram várias funcionalidades do GSAN entre si ou, até mesmo, a integração do GSAN com outros sistemas ligados à atualização das informações de sua base de dados. Por exemplo: a integração do GSAN com o módulo de celulares Android para a impressão simultânea de contas em campo.

Atualmente, os manuais disponíveis no Dokuwiki são sete:

• 1. Manual de Processos de Negócios - Cobrança - Negativação;
• 2. Manual Nova Sistemática de Cobrança da Caern;
• 3. Manual do Sistema para Acompanhamento de OS de Cobrança por Resultado - Caern;
• 4. Manual do Sistema de Acompanhamento de Ordens de Serviços;
• 5. Manual do Sistema para Acompanhamento de OS de Cobrança;
• 6. Manual de Atualização Cadastral Via Dispositivo Móvel.
• 7. Manual de Impressão Simultânea Android - GSAN.

A seguir, veremos os principais elementos tipográficos para a composição de um texto no Dokuwiki.

Para mais dicas de formatação consulte aqui.