Boas práticas para desenvolver software livre e aberto: Documentação

La documentação é e deve ser uma parte fundamental do processo criativo e planejamento de toda a atividade humana, e mais no campo tecnológico, especialmente na área de Desenvolvimento de software.

El propósito de toda documentação deve ser ele ensinar terceiros (usuários, administradores, mantenedores ou outros desenvolvedores), que geralmente não estão familiarizados com o produto (código, aplicativo ou sistema), como é criado sua estrutura, sua operação e ainda se possível, o motivo da sua criação e a sua forma de concepção e funcionamento.

Além disso, no caso específico de A documentação do software livre é vital, pois permite garantir integralmente o transferência de conhecimento e capacitação necessário para o cumprimento satisfatório do 4 liberdades promovidos por ele, que são:

• 0: A liberdade de executar o programa como quiser, para qualquer propósito.
• 1: A liberdade de acessar e estudar um programa e alterá-lo ou adaptá-lo para seu próprio benefício.
• 2: A liberdade de compartilhar ou redistribuir cópias para divulgá-las e / ou ajudar outras pessoas.
• 3: A liberdade de distribuir cópias de suas versões modificadas a terceiros.

Uma boa documentação possibilita, portanto, que o produto criado:

• É usado corretamente e é mais facilmente ensinado e aprendido.
• Seja totalmente compreendido por aqueles que desejam modificá-lo para melhorá-lo ou adaptá-lo.
• Seja compartilhado e recebido com mais confiança, entre todos os potenciais conhecidos e estranhos.
• Tenha uma massa melhor junto ao público.

Boas práticas: Documentação

Fundamentos

No caso de Desenvolvimento de Software Livre e Código Aberto, geralmente, principais usuários da documentação em relação ao design do produto, são aqueles que são ou serão, o responsável pela manutenção do mesmo. E sem boa ou nenhuma documentação, a única alternativa viável é explorá-lo diretamente, para alcançar entender seu design e função.

Não criar uma boa documentação quando se trata de desenvolver software livre, código aberto ou qualquer outro tipo de software, é para enviar aos seus possíveis destinatários (usuários, administradores, mantenedores ou outros desenvolvedores) encontrar um caminho na selva sem um mapa ou uma bússola.

Crie uma boa documentação para cada Software Livre, Código Aberto também é benéfico, uma vez que, embora documentar tem um custoO investimento, se feito corretamente, vale a pena. Porque, o mundo de Software está cheio de histórias sobre códigos legados programas, aplicativos ou sistemas antigos ou atuais, que poucas pessoas ousam tocar, porque quase ninguém entende. Os programadores se concentram em criar código e não em documentá-lo correta e completamente. E isso deve ser remediado.

Boas práticas na documentação em arquivos de texto README

No caso de Software Livre e Código Aberto, a documentação costuma ser restrita a arquivos de texto, quando é criada por indivíduos ou pequenos grupos de programadores ou comunidades. Mas, até criar uma documentação simples usando um simples arquivo de texto README.md (ou .txt) você pode ter o seu melhores ou boas práticas, dicas ou guia útil de criação para levar a terceiros as informações mais completas e detalhadas necessárias sobre o que foi criado.

Para o nosso artigo, pegamos o Boas práticas concebida e divulgada pela "Código para Iniciativa de Desenvolvimento" De Banco Interamericano de Desenvolvimento, que em resumo nos diz que uma boa documentação baseada em um arquivo de texto README.md (ou .txt) Deve ser estruturado da seguinte forma:

Estrutura de arquivo README recomendada

• Descrição e contexto: Seção onde você deve descrever as funcionalidades, o contexto onde foi desenvolvido e os problemas de desenvolvimento que ajudou a resolver.
• Guia do usuário: Seção onde as instruções para o usuário final sobre como começar a usar a ferramenta digital devem ser mencionadas.
• Guia de instalação: Seção onde devem ser mencionadas as instruções de instalação para reutilização e configuração da ferramenta digital. Esta seção é destinada a desenvolvedores.
• autores Seção onde devem ser dados os créditos aos colaboradores da ferramenta.
• Licença para o código da ferramenta: Seção onde devem ser especificadas as permissões concedidas a terceiros para reutilização da ferramenta digital.
• Licença para a documentação da ferramenta: Seção onde deve ser mencionado o tipo de licença contida na documentação criada.

Nestes boas práticas, eles também recomendam adicionar ao Documentação do arquivo README para torná-lo mais completo, as seguintes seções:

• Como contribuir: Seção que explica aos novos desenvolvedores o processo de contribuição para os projetos.
• Código de conduta: A seção que explica o código de conduta estabelece as normas sociais, regras e responsabilidades que os indivíduos e organizações devem seguir ao interagir de qualquer forma com a ferramenta digital ou sua comunidade.
• Distintivos: Seção que mostra os emblemas (pequenas imagens embutidas no README.md) que especificam de forma legível e concisa o estado da ferramenta.
• Versão: Seção que indica uma lista das versões da ferramenta digital e as funcionalidades adicionadas a cada versão.
• Agradecimentos: Seção que contém os agradecimentos a outras pessoas ou organizações que contribuíram de alguma forma para o projeto.

Para expandir essas informações, no Boas práticas em matéria de Documentação para o desenvolvimento de software livre, pelo "Código para Iniciativa de Desenvolvimento" De Banco Interamericano de Desenvolvimento você pode clicar no seguinte link: Documentação - Guia para publicação de ferramentas digitais. E em outras publicações, exploraremos a parte referente a boas práticas em avaliação e licenciamento De Software Livre e Aberto si mesmos.

Conclusão

Esperamos que este "postinho útil" sobre as «Buenas prácticas» no campo de «documentación» para criar ao desenvolver «Software libre y abierto», seja de grande interesse e utilidade, para todo o «Comunidad de Software Libre y Código Abierto» e de grande contribuição para a difusão do maravilhoso, gigantesco e crescente ecossistema de aplicações de e para «GNU/Linux».

E para mais informações, nem sempre hesite em visitar qualquer Biblioteca online como OpenLibra y jedit para ler livros (PDFs) neste tópico ou em outros áreas de conhecimento. Por enquanto, se você gostou disso «publicación», não pare de compartilhar com outros, em seu Sites, canais, grupos ou comunidades favoritos de redes sociais, de preferência gratuitas e abertas como Mastodonte, ou seguro e privado como Telegram.

Ou simplesmente visite nossa página inicial em DesdeLinux ou junte-se ao canal oficial Telegrama de DesdeLinux para ler e votar nesta ou em outras publicações interessantes sobre «Software Libre», «Código Abierto», «GNU/Linux» e outros tópicos relacionados a «Informática y la Computación»E o «Actualidad tecnológica».