Questões De Documentação Em Open Source
Muitos projetos de código aberto enfrentam desafios significativos geração e manutenção de alta qualidade, documentação do usuário final. Alguns desses desafios são bem conhecidos em engenharia de software e comum em toda a indústria de computadores tanto em open source e reinos proprietários. Outros são peculiar para projetos de código aberto.
Desafios Genéricos À Documentação Em Software
As causas da documentação do software pobre ou carente têm sido amplamente estudados dentro de engenharia de software acadêmico e industrial. A falta de progresso sugere que não há uma solução fácil, mesmo quando as causas podem ser identificados, e soluções são difíceis de encontrar. Eles incluem:
- Benefício direto: o valor da documentação é inversamente proporcional à capacidade de um indivíduo para escrever essa documentação. Como resultado, muitas vezes os desenvolvedores são reticentes a documentar completamente seu trabalho.
- Habilidades: escrever documentação requer um conjunto específico de habilidades que não são comumente encontrados dentro das comunidades de desenvolvimento open source.
- Time: escrever documentação requer tempo, o que é muitas vezes inexistente, principalmente na corrida para completar software por um prazo. Software desenvolvido utilizando o modelo de código aberto pode sofrer menos do que software proprietário, a este respeito, porque ele tem menos necessidade de se concentrar em prazos. No entanto, muitos projetos de código aberto, especialmente o usuário final projetos focados, comprometem-se a um rigoroso cronograma de lançamento.
- Mudança: durante o desenvolvimento, software muda frequentemente, exigindo alterações correspondentes na documentação. Isso torna tentador deixar a escrita de documentação até que o software está pronto e já não mudando. É claro que por esse tempo muitos detalhes serão esquecidos e o tempo que resta antes do lançamento quase certamente será muito curto.
- Bibliotecas: muito software é escrito em uma base componente ou biblioteca, considerando que é experimentado pelo usuário como um sistema inteiro. Mesmo muito boa documentação de um componente ou biblioteca pode ser irrelevante ou inúteis no contexto de um sistema inteiro.
- Level: muitos programadores têm sido profundamente imerso na indústria de software por anos. Eles têm um profundo conhecimento não só do seu próprio software, mas os computadores em geral. Isso pode tornar-se um desafio para os programadores a escrever de forma eficaz para os usuários finais, porque as suas visões do mundo diferem em muitos pontos importantes. Imagine um matemático de classe mundial tentando ensinar aritmética na escola. É claro que existem pessoas especiais, que pode ter sucesso em ambos os níveis, mas é raro.
Em contextos tradicionais de engenharia de software, a resposta normal a estas questões é empregar escritores técnicos, que têm dedicado tempo, as competências adequadas, e uma visão de mundo mais generalista do que os desenvolvedores de software. Escritores técnicos são trazidos para o fim do ciclo de vida de desenvolvimento de software, quando a estrutura do software é clara, mas antes que o software é liberado para beta testers, para mitigar as questões da mudança de software.
Desafios Para A Documentação Em Projetos De Código Aberto
As questões que agravam o problema em projetos de código aberto incluem:
- Percebida foco em desenvolvedores: projetos de código aberto, por vezes, parecem girar em torno de desenvolvedores de software para a exclusão de outros contribuidores. Isso é lamentável, como as melhores pessoas para escrever a documentação do usuário são os próprios usuários.
- Excitação: documentação escrita não é percebida como um excitante ou sexy atividade. Em projetos de código aberto onde os contribuintes têm significativamente mais ampla liberdade sobre o que contribuir, muito poucos deles contribuir para qualquer coisa que não excitá-los.
- Informações Difuso: a maior parte das informações geradas pelos projetos de código aberto é muitas vezes em listas de discussão, fóruns, e os logs de bate-papo. Poucos projetos têm mecanismos para integrar a informação útil na documentação formal.
Enfrentar O Desafio De Documentação
Esses problemas podem ser potencialmente compensado dentro de um projeto de código aberto de forma consciente e explicitamente valorizando documentação. Algumas das maneiras diferentes projetos open source fazer isso incluem:
- Exigir documentação estruturada junto com cada contribuição de código fonte. Isto é usado por muitas comunidades, como Perl e Plone, para manter a qualidade de suas bibliotecas contribuições dos usuários. Infelizmente, enquanto ele funciona bem para documentação nível de biblioteca, ele só funciona para novas contribuições, e por isso não pode ser usado no nível de sistema.
- Fazer listas de discussão, chat logs, relatórios de bugs e como muitas outras informações do projeto quanto possível acessíveis aos motores de busca e sistemas de bookmarking. As listas de discussão e chat logs contêm uma riqueza de informações sobre o projeto, e expondo-os para os motores de busca e outras ferramentas, os usuários podem ajudar-se a questões já respondidas.
- Incentivando os usuários novos, mas articulada, para contribuir documentação como sua primeira contribuição para o projecto. Novos usuários são ideais para escrever documentação em nível de sistema destinado a novos usuários. Eles têm o ponto de vista e experiência com o software atual no nível do sistema, em vez de no nível de biblioteca. A evidência mais comum disso é a lista FAQ, em que as questões levantadas repetidamente em listas de discussão e sessões de chat são respondidas. Wikis, sistemas de rastreamento de bugs, e FAQs são ótimos primeiros passos.
- Alocação de recursos explícitos à escrita documentação. Alguns projetos com acesso a financiamento externo (Eclipse, OpenOffice, SuSE Linux, etc.) usam alguns desses fundos para empregar escritores técnicos especializados, e esses projetos tendem a ter documentação do usuário final polido.
Talvez o aspecto mais importante da documentação em engenharia de software está escutando a questões e problemas dos utilizadores finais. Os usuários finais são a melhor forma de feedback (e em muitos casos apenas) que muitos projetos de obter. A documentação pode ser melhorados pela primeira respondendo perguntas imediatas dos usuários finais e, em seguida, voltar atrás para examinar e resolver as causas subjacentes dos problemas.
Outras Leituras
Exemplos de software de código aberto que fornece uma boa documentação incluem:
Informação conexa do OSS Watch:
Fonte: http://oss-watch.ac.uk/resources/archived/documentation
