Bones pràctiques per a desenvolupar programari lliure i obert: Documentació

La documentació és i ha de ser una part fonamental de l' procés creatiu i planificador de tota activitat humana, i més en l'àmbit tecnològic, sobretot en l'àrea de l' Desenvolupament de Software.

El propòsit de tota documentació ha de ser, el ensenyar a tercers (usuaris, administradors, mantenidors, o altres desenvolupadors), Que no solen estar familiaritzats amb el producte (codi, aplicació o sistema), Com està creada la seva estructura, el seu funcionament i fins si és possible, el per què de la seva creació i la seva forma de disseny i funcionament.

A més, en el cas específic de l' Programari Lliure la documentació és vital, Ja que la mateixa permet garantir plenament la transferència de coneixement i l'apoderament necessari perquè es compleixin satisfactòriament les 4 llibertats promogudes pel mateix, les quals són:

• 0: La llibertat d'executar el programa com es vulgui, amb qualsevol propòsit.
• 1: La llibertat d'accedir i estudiar un programa, i canviar-lo o adaptar-lo per al benefici propi.
• 2: La llibertat de compartir o redistribuir còpies per difondre el mateix i / o ajudar a altres.
• 3: La llibertat de distribuir còpies de les seves versions modificades a tercers.

Una bona documentació fa possible, per tant, que el producte creat:

• S'usi correctament, i s'ensenyi i s'aprengui més fàcilment.
• Sigui entès a profunditat, per aquells que desitgin modificar-lo per millorar-o adaptar-lo.
• Es comparteixi i sigui rebut amb més confiança, entre tots els possibles coneguts i desconeguts.
• Tingui una millor massificació entre el públic.

Bones pràctiques: Documentació

Fonaments

En el cas del Desenvolupament de l'Programari Lliure i Codi Obert, En general, els principals usuaris de la documentació relativa a el disseny del producte, són aquells que són o han de ser, els responsables de l'manteniment de la mateixa. I sense una bona o nul·la documentació, l'única alternativa viable és explorar directament el mateix, per aconseguir entendre el seu disseny i funcionament.

No crear una bona documentació a l'hora de desenvolupar Programari Lliure, Codi Obert o qualsevol altre tipus de programari, és enviar als seus possibles destinataris (Usuaris, administradors, mantenidors, o altres desenvolupadors) a buscar un camí a través d'una selva sense mapa ni brúixola.

Crear una bona documentació per a cada Programari Lliure, Codi Obert també és beneficiós, ja que, encara documentar té un cost, La inversió, si es fa correctament, val la pena. A causa de que, el món de l' Software està ple d'històries sobre codis heretat de vells o actuals programes, aplicacions o sistemes, que només poques persones s'atreveixen a tocar, perquè gairebé ningú ho entén. Els programadors s'enfoquen en crear codi i no en documentar-correcta i completament. I això ha de ser esmenat.

Bones pràctiques sobre documentació en arxius de textos README

En el cas del Programari Lliure i Codi Obert, Moltes vegades la documentació sol restringir-se a arxius de text, quan el mateix és creat per individualitats o petits grups de programadors o comunitats. Però, fins a crear una documentació senzilla mitjançant un senzill arxiu de text README.md (o .txt) pot tenir les seves millors o bones pràctiques, Consells o guia útil de creació per dur a tercers la més completa i detallada informació necessària sobre la creació.

Per al nostre article, hem pres les Bones pràctiques concebudes i divulgades per la "Iniciativa Codi per al Desenvolupament" del Banc Interamericà de Desenvolupament, Que de forma resumida ens diu que una bona documentació basada en un arxiu de text README.md (o .txt) ha d'estar estructurada de la següent manera:

Estructura recomanada de l'arxiu README

• Descripció i context: Secció on s'ha de descriure les funcionalitats, el context on va ser desenvolupat i els problemes de desenvolupament que va ajudar a resoldre.
• Guia d'usuari: Secció on s'han d'esmentar les instruccions a l'usuari final sobre com començar a utilitzar l'eina digital.
• Guia d'instal·lació: Secció on s'han d'esmentar les instruccions d'instal·lació per a reutilitzar i configurar l'eina digital. Aquesta secció està dirigida a desenvolupadors.
• autors Secció on s'han de donar crèdits als col·laboradors de l'eina.
• Llicència per al codi de l'eina: Secció on s'han d'especificar els permisos que s'atorguen a tercers per reutilitzar l'eina digital.
• Llicència per a la documentació de l'eina: Secció on s'ha d'esmentar el tipus de llicència que porta la documentació creada.

en aquestes bones pràctiques, També recomanen afegir a la documentació de l'arxiu README per fer-la més completa, les següents seccions:

• Com contribuir: Secció que explica als nous desenvolupadors el procés per contribuir a projectes.
• Codi de conducta: Secció que explica el codi de conducta estableix les normes socials, regles i responsabilitats que els individus i organitzacions han de seguir a l'interactuar d'alguna manera amb l'eina digital o la seva comunitat.
• Insígnies (badges): Secció que mostra les insígnies (petites imatges incrustades en el README.md) que especifiquen d'una manera llegible i concisa l'estat de l'eina.
• versió: Secció que indica un llistat de les versions de l'eina digital i les funcionalitats afegides a cada versió.
• reconeixements: Secció que conté els reconeixements a altres persones o organitzacions que hagin contribuït d'alguna manera a el projecte.

Per ampliar aquesta informació, sobre les Bones pràctiques en matèria de Documentació per al desenvolupament de l' programari Lliure, Per part de la "Iniciativa Codi per al Desenvolupament" del Banc Interamericà de Desenvolupament es pot fer clic al següent enllaç: Documentació - Guia per publicar eines digitals. I en altres publicacions explorarem la part referent a les bones pràctiques sobre la avaluació i llicenciament del Programari Lliure i Obert d'ells mateixos.

Conclusió

esperem que aquesta "petita i útil publicació" sobre les «Buenas prácticas» en l'àmbit de la «documentación» a crear a l'hora de desenvolupar «Software libre y abierto», Sigui de molt interès i utilitat, per a tota la «Comunidad de Software Libre y Código Abierto» i de gran contribució a la difusió de l'meravellós, gegantí i creixent ecosistema d'aplicacions de i per a «GNU/Linux».

I per a més informació, no dubtis sempre en visitar qualsevol Biblioteca en línia com a OpenLibra y jEdit per llegir llibres (PDFs) sobre aquest tema o altres àrees de coneixement. Per ara, si t'ha agradat aquesta «publicación», no deixis de compartir-la amb d'altres, en els teus llocs web, canals, grups o comunitats favorites de xarxes socials, preferiblement lliures i obertes com Mastodon, O segures i privades com telegram.

O simplement, visita la nostra pàgina d'inici en DesdeLinux o uneix-te a Canal oficial de Telegram de DesdeLinux per llegir i votar per aquesta o altres interessants publicacions sobre «Software Libre», «Código Abierto», «GNU/Linux» i altres temes relacionats amb la «Informática y la Computación», I la «Actualidad tecnológica».