DOCUMENTAÇÃO DE SITES

Transcrição

1 DOCUMENTAÇÃO DE SITES Necessidade ou preciosismo? A documentação de software ou site, mesmo sendo o carma de qualquer desenvolvedor, é extremamente necessária e auxilia na redução de horas preciosas na correção de problemas. Então vamos falar sobre a necessidade de documentação de um site, aspecto geralmente esquecido pelos desenvolvedores e empresas do ramo. Apesar de muitas empresas e até mesmo gerentes e líderes de projetos desprezarem esta etapa tão fundamental. Para muitos desenvolvedores, a criação de documentação técnica é a parte mais aterrorizante para se enfrentar em todo o processo de criação de um software, seja pela necessidade de escrever várias e várias páginas de texto, gráficos e desenhos ou ainda pela necessidade de largar aquilo que se aprendeu (programar) para fazer aquilo que não sabe bem (redigir). A documentação é cada vez mais importante e deve acompanhar todos os processos, desde a analise até a fase testes finais. Os responsáveis por coordenar essa atividade, que deve iniciar no briefing (conjunto de informações passadas em uma reunião para o desenvolvimento de um trabalho) e prosseguir até o final do projeto, é justamente o líder ou gerente do projeto. Devem ser documentadas mesmo as informações que pareçam irrelevantes no momento. Devem constar da documentação de um projeto o briefing do projeto, a equipe do projeto e suas atribuições, os wireframes (esqueletos dos websites, feitos pelos Arquitetos da Informação) do website, a documentação de conformidade técnica, toda e qualquer solicitação que o cliente faça (eduque o cliente a sempre mandar suas solicitações por e mail ou por escrito, pois isto é prova documental) e, por final, a documentação dos testes realizados. Normalmente, em grandes corporações existem pessoas e/ou equipes voltadas única e exclusivamente para a criação de documentação, sendo que o desenvolvedor fica restrito à codificação e comentários de seu código. Já no mundo "real", esta atividade é realizada pelo próprio desenvolvedor e demanda um bom conjunto de horas para planejar e criar cada uma de suas partes a fim de atender minimamente as necessidades do produto desenvolvido. Então, como não é possível evitar a criação da documentação técnica, vamos tentar amenizar um pouco sua horrível aparência usando ferramentas que auxiliam na tarefa de domar o monstro. Mas, antes disso, uma pequena apresentação do que é a documentação em si. 1

2 Alguns documentos podem melhorar bastante a resolução de problemas que costumam ocorrer durante o processo: Documentação de incidentes: o gerente de cada projeto tem uma planilha onde anota problemas que podem surgir durante o processo de criação do site, com as devidas datas. Exemplos: um designer do projeto adoeceu e por isso o resultado final atrasou três dias; o servidor de testes ficou fora do ar por problemas técnicos por oito horas. Este documento não é mostrado ao cliente, a não ser quando há problemas causados pelo próprio cliente. Exemplo: o cliente prometeu fotos e textos para uma determinada data e não as entregou. Esse tipo de documentação é importante para justificar eventuais atrasos na entrega de um site. A figura abaixo demonstra essa relação entre os relatos e os setores envolvidos no projeto. O controle dos registros de incidentes serve não somente para o projeto em desenvolvimento, mas também para futuros projetos, onde os incidentes ocorridos e relatados podem servir como mecanismo de prevenção de erros. Documentação de conformidade técnica: o líder do projeto (ou preferencialmente um analista de sistemas) levanta todas as necessidades que norteiam os sistemas de um site e faz um documento onde detalhadamente descreve desde as tecnologias que serão utilizadas (e porque foram escolhidas), até a modelagem dos bancos de dados e o fluxograma do sistema. Bem como qualquer outra funcionalidade ou particularidade especial dos sistemas do site. Documentação de testes: os testes de usabilidade do site (se ocorrerem) e os testes dos sistemas devem ser bem documentados. Se a equipe não contar com um testador de usabilidade ou de sistemas, é recomendável que terceirize esta parte. Por mais banal que possa parecer a princípio, é muito importante e não deixa de ser mais uma validação da qualidade do website desenvolvido. Como muitos programadores costumam dizer, quem desenvolve não é a pessoa mais apropriada para testar, pois instintivamente ela sabe onde estão os furos, e passa batido por eles. Mas vale lembrar que um bom analista de sistemas também está capacitado para fazer estes testes. 2

3 Uma boa prática é evitar papéis. Então, ao final do projeto, transforme todos os documentos do projeto em PDFs e grave um CD para cada projeto. Deixe isso guardado pelo tempo que julgar importante. Vale lembrar que essa documentação é um registro importante, para acompanhar a evolução de metodologias e até mesmo da equipe. Fluxogramas: tão antigos quanto a computação, os fluxogramas apresentam graficamente a sequência lógica das informações de um processo ou sistema, utilizando para isso vários elementos de geometrias diferentes que indicam cada uma das partes do processo. Sua importância, mesmo deixada de lado, é grande, pois a partir dele, inicia-se o projeto de um sistema eficiente e bem desenvolvido. Eles elementos que visualmente conseguem passar a lógica de todo um sistema desde os níveis mais altos de processamento até pequenas partes, permitindo assim uma visão geral do que realmente precisa ser feito dentro do sistema. Documentação de código: para muitos, a parte mais chata. Para outros, a mais importante. A documentação de código é feita basicamente de duas formas: comentários dentro do próprio código e geração de documentação online (ou física). No primeiro caso normalmente o desenvolvedor acredita que sua memória nunca irá falhar e que somente ele irá colocar a mão no sistema, deixando de documentá-lo e gerando problemas gigantescos para si e para outros profissionais. Um conjunto de comentários bem feito é tão importante quanto uma lógica bem estudada. Funções, constantes, inclusão de arquivos, campos de tabelas e outros elementos sempre proliferam de forma exponencial dentro do sistema, o que leva na maioria das vezes o desenvolvedor a simplesmente criar novos "remendos" com constantes "adicionais" ou variáveis novas, pois não se recorda onde está aquela função que formata determinado campo (quem não passou por isso?). Um pequeno exemplo de um código bem comentado pode ser visto a seguir: $database->setquery( $query ); $rows = $database->loadobjectlist(); // establish the hierarchy of the menu $children = array(); // first pass - collect children if ($rows) foreach ($rows as $v ) { $pt = $v->parent; $list $children[$pt] : array(); array_push( $list, $v ); $children[$pt] = $list;} // second pass - get an indent list of the items $list = mostreerecurse( 0, '', array(), $children, max( 0, $levellimit-1 ) ); 3

4 Observe que não são necessárias dezenas de linhas de comentários para compreender o que determinada área do sistema executa. Mas se estas simples linhas forem deixadas de lado, além de gerar um gasto desnecessário de horas à procura de erros, aumenta-se o nível de estresse de todos que irão mexer no código e principalmente de quem paga por ele. Modelos de dados: o modelo de dados reflete de uma forma gráfica (e lógica) a base de dados de um sistema, seus relacionamentos, entidades, chaves e tudo aquilo que é referente aos dados em si. Este modelo, junto com o dicionário de dados, é peça fundamental para o desenvolvimento de um sistema, sendo inclusive pensado e criado antes do início do desenvolvimento. Um bom modelo de dados bem pensado e bem estruturado não impacta somente em um bom código, mas também na desempenho da aplicação com um todo e na redução de horas de desenvolvimento equivocado. Para criá-lo são utilizadas ferramentas de modelagem de dados, as quais geram de forma gráfica as tabelas, índices, relacionamentos e tudo aquilo que tem a ver com a base de dados em si, podendo ser criados por meio de engenharia reversa ou ainda baseando-se nas necessidades do aplicativo que está sendo desenvolvido. As ferramentas mais conhecidas para modelagem de dados dentro do mundo livre são o DBDesigner ( MySQL Workbench ( e também o PGDesigner ( as quais possuem funcionalidades diferentes e dispõem de versões tanto para Linux quanto para Windows. Dicionário de dados: Como o próprio nome sugere, o dicionário de dados nada mais é que um arquivo ou documento que define a organização básica dos dados do banco. Nele são informadas as tabelas, os campos, suas definições, tipos e descrições (para que serve este campo?). Um exemplo simples de um dicionário de dados pode ser visto a seguir: Tabela: CadastroCliente Campo Tipo Tamanho Propriedades Descrição id_cadastro Smallint 5 Auto-increment ID do registro do cadastro na_nome Varchar 50 Not null Nome do dono da empresa na_empresa Varchar 50 Null Nome da empresa ad_ Varchar 75 Not Null Endereço de principal nu_fone Varchar 14 Null Telefone de contato 4

5 Com um arquivo destes, mesmo simplório, em conjunto com o modelo de dados, a possibilidade de erro na hora do desenvolvimento fica extremamente reduzida, quando falamos de acesso a dados na base, além de economizar neurônios que muitas vezes estão sendo usados para armazenar a informação que o campo varcodsysfil01 é o código de uma filial. 5

6 O WIREFRAME Documento deve especificar elementos de uma página, não design gráfico. Do ponto de vista do design gráfico, o documento que o arquiteto da informação gera para especificar os elementos que vão compor uma página (wireframe) deve ser o mais simples possível. Esse documento deve servir como mera referência para o designer gráfico da página, que pode até encontrar uma disposição melhor para os elementos dentro de sua criação. Se o wireframe é repassado com o grid de alinhamento definido, tamanhos de fontes e até tipografia, o designer pode se sentir engessado demais. Por outro lado, o wireframe normalmente é entregue ao cliente para aprovação antes de ficar pronto o design gráfico, ou seja, um monte de rabiscos numa folha de papel causa uma impressão pouco profissional. É por esse motivo que muitos arquitetos da informação capricham demais na apresentação do wireframe. O exagero começa quando o arquiteto se preocupa se alguém vai achar feio seu wireframe. Wireframe não é pra ser bonito, é pra ser entendido. Antes de entregar wireframes para os clientes, avise de que se trata de um esboço feito para poder discutir logo os elementos que vão compor a página. Além de explicar que depois de definido o wireframe será feito o design gráfico, uma maneira de esclarecer isso para o cliente é escrever o seguinte em cima do documento: Este wireframe não especifica design gráfico. Sua função é apresentar os elementos que vão compor a página. É possível que na primeira vez o cliente estranhe, mas isso pode ser compensado com uma boa discussão em cima do wireframe. Para enfatizar ainda mais o estado de esboço, risco com uma caneta em cima o que for para mudar. Dica: Só não deixe que o cliente pegue a caneta, senão pode ser que ele se empolgue demais... 6

7 Nem todos os clientes terão tempo para discutir desse jeito, mas oferecer a oportunidade é importante para que ele sinta que tem controle (ou participação) sobre o projeto. Ressalte que, uma vez aprovado o wireframe, não será possível voltar atrás em suas definições. O wireframe da figura 1 é um exemplo que foi apresentado para um cliente bastante participativo e gerou uma excelente discussão (note os rabiscos). Depois da reunião, foram feitas várias alterações (figura 2) no wireframe. Figura 1 Figura 2 Passando o wireframe para o designer gráfico e explicado que ele teria liberdade para mudar a disposição dos elementos da página, desde que mantivesse os pesos relativos. Veja como foi bem aproveitada liberdade: Esse não é o layout final do projeto, que ainda está sendo desenvolvido, mas é um bom exemplo de utilização de wireframes simples. 7

8 8

9 BIBLIOGRAFIA Documentação: Acessado em 31 de março de Documentação: Fonte: Acessado em 1 de abril de Wireframe: Acessado em 31 de março de