6b-Manual Do Desenvolvedor

8/9/2019 6b-Manual Do Desenvolvedor

1/24

I n te l ignc ia Pro theus

Guia da documentao - manual do desenvolvedor 1

M a n u a l p a r a

o a n a lis t a d e

d es en v o lv im en t o


2/24



Sumrio

Sumr io ............................................................................................................................. 2

I n t r o d u o ....................................................................................................................... 3

Obje t i vo des te gu ia .................................................................................................... 5

Elaborao de um bom con tedo de docum entao .............................. 5

Help de p rogram as ...................................................................................................... 7

Help de cam pos , pe rgun tas e mensagens de e r ro / so luo ............. 14


3/24



INTRODUO1

Sistemas de ajuda (help) costumam ser ignorados ou consultados apenas emltima instncia, pois geralmente os usurios no vem de imediato umarelao favorvel de custo/benefcio no acesso a tais sistemas. Experinciasinfrutferas com o help de diversas aplicaes existentes fazem com que osusurios nem cogitem sobre sua utilizao quando necessitam algumesclarecimento. A qualidade do help est relacionada a seu contedo e sestruturas de acesso ao mesmo.

Sistemas de help online tradicionais so geralmente orientados funes, nosendo relacionados s tarefas dos usurios e ao contexto corrente de suainterao. Isto se deve, principalmente, estratgia de desenvolvimento dohelp e falta de um modelo de help que considere os fluxos de tarefas dos

usurios. Ou seja, estas informaes solicitadas/obtidas dizem respeito aocontexto da funo utilizada pelo usurio e no ao contexto da tarefa que ousurio est tentando realizar. Esta descontinuidade com a situao de uso(contexto da tarefa) que o usurio se encontra o grande problema na maioriadas aplicaes.

A interface da aplicao , uma metamensagem dos desenvolvedores para osusurios. Ela, implcita ou explicitamente, representa como o desenvolvedorpensou a aplicao e como a construiu (e por qu). Neste sentido, o helponline um componente importante, porque atravs dele que osdesenvolvedores esto mais capacitados a mostrar diretamente como eles

pensaram e conceberam a aplicao.

Devido a isto, os desenvolvedores do help devem fornecer tanto um acessofacilitado quanto informaes claras para que os usurios no apenas voltem aconsultar estes sistemas, mas tambm, tenham um retorno produtivo destasconsultas.

A documentao de sistemas e sua importncia

A documentao, vista como uma ferramenta de auxlio a ser utilizada nomomento de sua necessidade por todas as pessoas envolvidas com o sistema,

precisa, para cumprir este papel, ser elaborada seguindo a metodologiaadotada, bem como necessita ser atualizada sempre que houver umamodificao.

1Revelando as Affordances do Designer via Sistemas de Help e Interjeies de Comunicabilidade

Milene Selbach Silveira e Simone Diniz Junqueira Barbosa PUC-Rio - Maio, 2001


4/24



O ambiente complexo e rapidamente mutvel em que est inserido odesenvolvimento de software agravado pelas inconsistncias, falta dedocumentao, redundncias, dificuldades de acesso etc.

Dados estatsticos demonstram que de 47% a 62% do tempo gasto em

manuteno de sistemas dispendido na tentativa de entender o programa, eque ler o cdigo fonte custa 3,5 vezes mais do que ler a documentao. Almdisso, 53% dos defeitos so descobertos em trechos tidos como corretos e10% so introduzidos durante as alteraes. Outros 64% dos defeitos so delgica, enquanto 79% so causados por entendimento incorreto do problema.Ainda, novos modelos organizacionais (analista de informao, pool deanalistas lgicos, pool de analistas fsicos e programao interna outerceirizada) implicam na necessidade de fazer perfeita e completadocumentao.

Fatores que demonstram a importncia da documentao de sistemas so2:

A legislao brasileira (Lei 9.430/96, de 27 de dezembro de 1996)obriga as pessoas jurdicas a manterem documentao atualizada deseus sistemas, para fins de auditoria por parte de organismos oficiais. Alei reproduz preceitos, antes esparsos na Legislao Federal, referentesao acesso, reteno e guarda de documentao para efeito defiscalizao para possibilitar sua auditoria;

Resgate do know-how da organizao: muitos sistemas podem edevem ser considerados ativos da organizao, e como tal devem teruma documentao confivel e segura;

Deteco de falhas eventualmente existentes nos sistemas: na atividadede documentao de sistemas, possvel encontrar erros de lgica quepodem provocar resultados inesperados;

Liberao de recursos computacionais: a atividade de documentao desistemas tambm permite reportar programas e trechos de cdigo queno esto sendo utilizados;

Padronizao para a certificao de qualidade: quando um sistema fazparte de um processo que est sendo preparado para uma certificao,torna-se necessrio que tenha suas funes documentadas para efeitode auditoria;

Maior facilidade de entendimento do sistema: mesmo um profissional deinformtica que no conhea o sistema ter maior facilidade deentendimento pela utilizao da documentao no lugar da utilizaodos fontes dos programas;

2KETIS, D. Terceirizando a documentao de sistemas. Developers CIO Magazine. Rio de Janeiro, v. 3, n.36, p. 32-33, ago. 1999


5/24



Comunicao eficaz das informaes entre as reas envolvidas: quandoa comunicao entre as reas acontece formalmente e apoiada emdocumentos padronizados, a possibilidade de falha no entendimento ficareduzida. A formalizao auxilia no s o destinatrio mas o prprioremetente, visto que sua demanda ser melhor explicitada.

OBJETIVO DESTE GUIA

O objetivo deste guia fornecer as diretrizes para o programador ou analistade sistemas elaborar o contedo do help dos programas, campos e perguntasdo sistema Protheus. No caso dos help de programas, tais contedos devemdar subsdios para a rea de documentao desenvolver, diagramar e efetivar

esse material nos padres de documentao elegidos.

ELABORAO DE UM BOM CONTEDO DE DOCUMENTAO

Para elaborar um bom contedo para a documentao de um programa importante se colocar na posio do usurio e perceber quais seriam asdvidas mais frequentes e como elas poderiam ser resolvidas.

Nveis de Af f o rdanc e 3 em sistemas de Help

Evidencia-se que o desenvolvedor conseguiu se comunicar com os usuriosquando os mesmos percebem as affordances da aplicao4.

Estas affordances projetadas pelo desenvolvedor podem ser classificadas emtrs nveis:

Operacional; Ttico; Estratgico.

As affordances de nvel operacional so relativas s aes imediatas individuaisque o usurio tem que executar, sendo ligadas diretamente aos cdigosinterativos utilizados. Pode-se dizer que estas affordances respondem aperguntas do tipo: O que isto?

3 Affordance = dicas visuais (grficos), capacidade de perceber/transmitir significados, esforo para oentendimento, nvel de percepo e proximidade com o usurio.4de Souza, C.S.; Prates, R.O.; Carey, T. Missing and Declining Affordances: Are these appropriate concepts?

No.1, Vol.7, July 2000. Rio de Janeiro, RJ, Brazil. pp. 2634.


6/24



J as affordances de nvel ttico so relativas a um plano ou seqncia deaes para executar determinada tarefa. Pode-se dizer que estas affordancesrespondem a perguntas do tipo: Como fazer isto?

Por fim, as affordances de nvel estratgico so relativas s conceitualizaes edecises envolvidas na formulao do problema ou processo de resoluo doproblema, e ao valor da tecnologia embutida na aplicao. Pode-se dizer queestas affordances respondem a perguntas do tipo: Por que bom/devofazer isto?

Mas como estes nveis de affordance relacionam-se aos sistemas de help?

Relao com as Dvidas Freqentes dos Usurios

Quais as dvidas mais freqentes dos usurios? Como elas poderiam ser

relacionadas aos nveis de affordances do desenvolvedor?

O que os usurios gostariam de ter, quando pedem socorro aplicao (help),so respostas para suas dvidas mais freqentes5 resumidas na tabela abaixo.

Tipo de Pergunta Exemplos de PerguntasInformativa Que tipo de coisas eu posso fazer com este programa?Descritiva O que isto? O que isto faz?Procedimental Como eu fao isto?Interpretativa O que est acontecendo agora? Por que isto aconteceu? O

que isto significa?

Navegacional Onde estou? De onde vim e para onde posso ir?Escolha O que posso fazer agora?Guia O que devo fazer agora?Histrico O que eu fiz?Motivacional Por que eu devo usar este programa? Como ele ir me

beneficiar?Investigativa O que mais devo fazer? Esqueci algo?Tabela: Taxonomia de Dvidas dos Usurios

As perguntas de tipo Informativa e Descritiva podem ser vistas como questesde nvel operacional, pois esto ligadas a aes diretas (operacionais) dousurio.

J as perguntas de tipo Procedimental podem ser vistas como questes denvel ttico, questionando como determinado problema pode ser resolvido.

5 Roesler, A.W.; McLellan, S.G. What Help Do Users Need? Taxonomies for On-line Information Needs &

Access Methods. In Proceedings of CHI95, ACM Press, 437-441. 1995.


7/24



As perguntas Interpretativas e Motivacionais, detalham os porqus dedeterminadas escolhas ou o significado das mesmas, dentro do contexto deuso do usurio, estando no nvel estratgico.

As perguntas de tipo Navegacional, Escolha, Guia, Histrico e Investigativa so

um misto de nvel operacional e ttico com estratgico, pois suas respostasvo indicar no apenas o que fazer, de que forma (que mtodo usar: o queposso/devo fazer? e como?), mas tambm por que motivo (devo fazer algo poralgum motivo).

HELP DE PROGRAMAS

Segundo a MDS/M, os desenvolvedores devem preparar/modificar o contedodos helps de programa na fase de criao e manuteno dos mesmos(procedimento o 3.3 Codificar componentes e executar teste unitrio nafase de Construo para o Ciclo Completo e procedimento 1.4 Codificarcomponentes e executar teste unitrio na fase de Construo para o CicloAbreviado).

Neste sentido importante descrever, com a maior quantidade de detalhes,todas as caractersticas do programa.

Sempre observar e descrever: contexto do programa (mdulo, fluxo de operao etc) finalidade do programa; informaes conceituais sobre o programa; procedimentos para uso do programa (roteiro e exemplos); tabelas utilizadas; parmetros utilizados; caso houver, lei que deu origem criao da rotina; especificaes ou diferenas entre os pases que a usam; toda e qualquer informao importante inerente rotina.

Exemplos de help de programa:

1 EXEMPLO: Programa CTBA010 Calendrio Contbila. Modelo final j documentado em robohelp (calendario_contabil.htm)

pela equipe de documentao. O que deve-se observar neste exemploso os elementos que compem o contedo do material.


8/24



Observar os tpicos conceituais destacados:

Exerccio Social


9/24



Perodos contbeis


10/24



Reabrindo um Exerccio j Encerrado

Note aqui feita uma relao de rotinas relacionadas, como o caso deEncerramento Exerccio (CTBA400)


11/24



Tabelas utilizadas (dados tcnicos)

Neste exemplo, notamos todos os componentes necessrios para um bomcontedo, como definio da rotina, esclarecimento de conceitos, exemplos,dicas, descrio de tabelas usadas, rotinas relacionadas, procedimentos de usoetc...

2 EXEMPLO: Rotina MATR995 Emisso Livro CIAPa. Modelo final j documentado em robohelp (matr995.htm) pela equipe de

documentao. O que deve-se observar neste exemplo so os elementosque compem o contedo do material.


12/24



Procedimentos para emisso do livro:


13/24



Tabelas utilizadas


14/24



HELP DE CAMPOS, PERGUNTAS E MENSAGENS DE ERRO/ SOLUO

No caso dos helps de campos e perguntas, o contedo includo diretamentena ferramenta ATUSX, conforme MDS/M (procedimento 3.2 Construir Bancode Dados Fase de Construo do Ciclo Completo ou procedimento 1.3 Construir Banco de Dados Fase de Construo do Ciclo Abreviado).

Neste sentido importante descrever, com a maior quantidade de detalhes,todas as caractersticas do campo e da pergunta a serem documentados.

Sempre observar e descrever: finalidade da pergunta ou campo; as Opes (caso for multipla escolha); o F3, se houver; as validaes, se houvrem; qualquer outra informao importante que modifique o resultado darotina.

Exemplos de help de campos:

Campo CT1_CONTA - Cdigo da Conta Contbilb. Descrio na ferramenta ATUSX


15/24



b. Visualizao no sistema do help de campo CT1_CONTA


16/24



Campo CT2_DEBITO - Cdigo da Conta Contbilc. Descrio na ferramenta ATUSX


17/24



d. Visualizao no sistema do help de campo CT2_DEBITO


18/24



Exemplo de help de perguntas:


19/24



Pergunta 05 do grupo CTC400 Consulta do Razo Contbila. Descrio na ferramenta ATUSX


20/24



b. Visualizao do help no sistema do help da 5ta pergunta do programaCTBC400 Consulta do Razo Contbil


21/24



No caso dos helps de mensagens de erro/soluo, o contedo tambm

includo diretamente na ferramenta ATUSX. Porm na MDS/M, diferentementeaos casos anteriores, o procedimento o 3.3 Codificar componentes eexecutar teste unitrio na fase de Construo para o Ciclo Completo eprocedimento 1.4 Codificar componentes e executar teste unitrio na fase deConstruo para o Ciclo Abreviado. Isto ocorre pois as mensagens soconstrudas e utilizadas no cdigo fonte alterado ou criado.

Neste sentido importante descrever, com a maior quantidade de detalhes,todas as caractersticas do mensagem e principalmente, se for uma mensagemde erro, a possvel soluo.

Sempre observar e descrever: a mensagem propriamente dita; opes e esclarecimentos adicionais, se necessrio; soluo, para os casos de erro ou para elencar possibilidades que o

usurio tem para contornar o propsito da mensagem.

Exemplos de help de mensagem de erro/soluo:

Mensagem NOALIQINTa. Descrio na ferramenta ATUSX


22/24



b. Visualizao do help da mensagem erro/soluo NOALIQINT


23/24



Mensagem SINBLOQa. Descrio na ferramenta ATUSX


24/24


b. Visualizao do help da mensagem erro/soluo SINBLOQ

6b-Manual Do Desenvolvedor

Documents

Transcript of 6b-Manual Do Desenvolvedor