A importância da Documentaçāo

Este texto busca explorar as motivações para; e as instruções gerais sobre como se fazer uma boa documentação. Partimos de um caso em que a documentação de um mesmo produto dá duas caras diferentes a ele e analisamos como podemos atuar no nosso contexto enquanto Possibilita.

Um dos motivos para os computadores se tornarem ferramentas praticamente indispensáveis nas nossas vidas foi a forma como os responsáveis por vendê-los e seus produtos relacionados encararam o mercado. Nos anos 70, com os avanços da microeletrônica, foi possível fabricar mais computadores, cada vez mais rápidos (como a lei de Moore sugere) e mais baratos. Na entrada dos anos 80, o maior fabricante era a IBM, que vendia computadores voltados aos consumidores executivos, que basicamente os utilizavam para processar grandes conjuntos de dados. Para tanto, contratavam pessoal altamente especializado no assunto e somente este pessoal era capaz de lidar com estas máquinas. Notavelmente, a maioria dos outros fabricantes se especializavam em vender computadores e programas de computador que fossem compátiveis com as máquinas da IBM. Entre os empreendedores dispostos a mudar esta visão, vamos destacar dois aqui: Steve Jobs e Richard Stallman. Steve Jobs (fundador da Apple Inc) via nos computadores o potencial de se tornarem as máquinas mais amigáveis que você pudesse ter dentro de casa, como inspirado nas criações do Xerox PARC. Segundo ele, computadores deveriam ser construídos baseados em uma experiência fechada para o usuário: ele entra, faz as coisas e sai. Há pouco espaço para customização desta experiência, e somente aqueles que te vendem o produto podem fazer alterações. Richard Stallman (fundador da GNU foundation) via nos computadores um meio tanto de fazer negócios quanto de se expressar. Segundo ele, se você faz um programa que você gosta, você deve dividí-lo com as outras pessoas. Isso não te impede de usá-lo para ganhar dinheiro vendendo serviços que utilizem este seu programa. Sob esta perspectiva, ele começou um movimento hoje reconhecido pelo modelo Open Source de produção: escrever programas de computador que fossem abertos para uso e desenvolvimento. Este pensamento foi expandido para outras áreas e, diante deste ideal, temos iniciativas similares, como os modelo Open Hardware (fazer hardware sob esta mesma perspectiva) e o ideal Open Data (todos os dados coletados em pesquisas devem ser públicos). Nesta linha de pensamento, enxergamos o projeto Possibilita como uma iniciativa de disponibilizar conhecimento sobre facilidades de natureza biomédica para a população brasileira em toda a sua formação.

Sob esta perspectiva de produção, vemos que todo produto deve ser documentado antes de ser entregue. Enxergando sob a visão de Steve Jobs, a documentação dos produtos deve ser feita com duas pessoas em mente: o usuário (que vê somente o produto final, e suas interações são encapsuladas de forma a não ver os processos internos da máquina) e o técnico em manutenção (que deve realizar seus reparos de forma a não expor aos usuários as entranhas do produto). Este modelo funcionou muito bem, haja visto que este pensamento cresceu dos empreendedores da Apple para aqueles que produziram acessórios para os computadores da empresa mencionada, como, por exemplo, a Hewlett Packard, que fabricou impressoras para os computadores Apple nos anos 80 com instruções bem simples e fornecendo um serviço de assistência muito bom comparado aos concorrentes. Por outro lado, a visão de Richard Stallman prevê um documentação unificada, já que o usuário final pode ser um consumidor comum, mas da mesma forma pode ser alguém que vá utilizar este programa para fornecer um serviço e que pode fazer alterações nele para satisfazer as necessidades do que for prestado. Um exemplo famoso de um programa que possuía, no tempo do seu lançamento, uma documentação forte para ambos usuários foi o sistema operacional Linux, desenvolvido por Linus Torvalds a partir de ferramentas desenvolvidas previamente por Richard Stallman. Apesar de ser voltado para um público mais especializado, o Linux conseguiu atingir um base de usuários relativamente grande no seu lançamento pela acessibilidade de sua documentação, tanto para o usuário comum como o fornecedor de serviços.

O grande problema desta visão open source da documentação encontra-se no que de fato acontece com software produzido desta maneira. Jonathan Blow, desenvolvedor de jogos, uma vez tuitou: “OPEN SOURCE SOFTWARE AUTHORS HAVE NO RESPECT FOR USERS and create giant externalities of wasted time and frustration”. Praticamente ao mesmo tempo, Henry Smith, programador ativista do movimento open source, tuitou enquanto pensava sobre os programas que ele produzia: “like there’s people doing serious grown-up stuff which is affected by 30 second decisions I make in my underpants on a sunday morning”. Em suma: como todo mundo pode contribuir com software open source, então teremos todo o tipo de gente neste cenário, incluindo pessoas que fazem isso por profissão, concebem planejamentos sérios acerca dos serviços que prestarão e dependem de programas feitos por pessoas que fazem isso por diversão e não precisam provar nada para ninguém. De toda forma, estes produtos acabam por ser documentados de maneiras diferentes, e nem sempre a referência atinge corretamente o usuário.

Sendo assim, podemos enxergar os diversos erros que podem surgir neste modelo e que, se queremos que o nosso projeto tenha sucesso, devemos evitar. Instruções desatualizadas, dados incorretos e instruções caóticas são frequentementes encontradas em projetos abertos, muitas vezes porque aqueles que escrevem a documentação nem sempre sabem quem a lerá ou para quê aquelas instruções serão utilizadas. No caso do Possibilita, este público-alvo já foi identificado: queremos atingir a população de pessoas deficientes que querem utilizar o computador. Aqui, veremos que há pessoas de todos os gêneros, classes socias, níveis de estudo, capacitações e expectativas acerca das instruções que forneceremos. Posto isto, a pergunta se torna: como escrever a documentação para os nossos projetos? Diante da visão histórica, é desejável que ela seja simples (como a visão de Steve Jobs para seus produtos) mas ao mesmo tempo compreensível o suficiente para que o usuário tenha controle para tomar decisões de alteração no projeto diante da sua necessidade (como a visão de Richard Stallman para software open source).

Uma referência para descrição de projetos é o “Manual do Desenhista de Máquinas” (PROTEC, 1996). Nele, além de explicar sobre técnicas de desenho e execução de máquinas, vemos que, de uma forma geral, um projeto é descrito a partir de seus elementos fundamentais, que comporão partes maiores, que farão parte de peças ainda maiores, e, assim em diante, descreverão o projeto final. Cada componente pode ser descrito por um desenho (um diagrama de vistas, por exemplo) contendo especificações como tamanhos, materiais e acabamentos; e a forma como os componentes se encaixam podem ser descritas através de um outro desenho (uma vista explodida, por exemplo), mostrando a relação espacial entre todos os componentes de um projeto. Cabe esclarecer que esta referência é extremamente técnica para os nossos fins: nem todos os usuários da nossa documentação tem acesso a uma gama grande de ferramentas ou até mesmo de conhecimento técnico acerca dos projetos que sugeriremos. We will need to apply some design to it

Uma melhora nesta linha de pensamento é descrita por Andrew Haslam em seu livro “O Livro e o Designer”. Quando descreve como o designer deve abordar instruções, ele cita que a solução mais comum (e provavelmente a mais eficiente) é o diagrama de processos. “Se cuidadosamente projetados e bem esquematizados, os diagramas podem transmitir explanações sem ajuda de palavras.” Como exemplo, ele cita os manuais da Hewlett Packard, que contém imagens descritivas da ação acompanhados de um texto explicativo para cada passo; e os diagramas de montagem dos blocos Lego, que notavelmente são os mesmo em todos os lugares do mundo já que as instruções contém somente imagens e, portanto, não necessitam de tradução. Inclusive, todos eles seguem o mesmo formato: o manual descreve quais peças utilizar e mostram como encaixar cada uma das peças para a construção do modelo final. Estes exemplos demonstram uma visão de como instruções devem ser encontrada no “Manual do desenhista de máquinas”, mas voltadas para um público não-técnico, e contribuem para um mesmo modelo de documentação.

Idealmente, podemos dizer que nossas documentações devem ser como receitas: queremos esclarecer quais os componentes que serão usados nos nossos projetos para, em seguida, mostrar como que esses componentes se relacionarão por meio de instruções simples (citando David Allen: “tem que ser algo que você dê conta de fazer assim que você acorda”) e de imagens que exemplifiquem cada passo. Cada passo pode conter também especificações técnicas mais profundas para que o usuário mais curioso sinta-se à vontade para fazer alterações no projeto.