Buone pratiche per sviluppare software libero e aperto: documentazione

La documentazione è e dovrebbe essere una parte fondamentale di processo creativo e pianificazione di tutta l'attività umana, e più nel campo tecnologico, soprattutto nell'area di Sviluppo software.

El scopo di tutta la documentazione deve essere lui insegnare a terze parti (utenti, amministratori, manutentori o altri sviluppatori), che di solito non hanno familiarità con il prodotto (codice, applicazione o sistema), come viene creato la sua struttura, il suo funzionamento e anche se possibile, il motivo della sua creazione e il suo modo di progettare e di operare.

Inoltre, nel caso specifico di La documentazione del software libero è vitale, poiché consente di garantire integralmente il trasferimento di conoscenze e responsabilizzazione necessario per il soddisfacente adempimento del 4 libertà promosso da esso, che sono:

• 0: La libertà di eseguire il programma come preferisci, per qualsiasi scopo.
• 1: La libertà di accedere e studiare un programma e modificarlo o adattarlo a proprio vantaggio.
• 2: La libertà di condividere o ridistribuire copie per diffondere le stesse e / o aiutare gli altri.
• 3: La libertà di distribuire copie delle versioni modificate a terzi.

Una buona documentazione permette, quindi, che il prodotto realizzato:

• È usato correttamente ed è più facile da insegnare e apprendere.
• Essere compreso a fondo da coloro che desiderano modificarlo per migliorarlo o adattarlo.
• Essere condiviso e ricevuto con più fiducia, tra tutti i potenziali conoscenti e sconosciuti.
• Avere una massa migliore tra il pubblico.

Buone pratiche: documentazione

Basi

Nel caso di Sviluppo di software libero e open source, in genere, principali utenti della documentazione relativi al design del prodotto, sono quelli che sono o saranno, i responsabile della manutenzione dello stesso. E senza una buona o nessuna documentazione, l'unica alternativa praticabile è esplorarla direttamente, per ottenere comprenderne il design e la funzione.

Non creare una buona documentazione quando si tratta di sviluppare software libero, open source o qualsiasi altro tipo di software, è da inviare ai suoi possibili destinatari (utenti, amministratori, manutentori o altri sviluppatori) per trovare un modo attraverso una giungla senza una mappa o una bussola.

Crea una buona documentazione per ciascuno Software libero, open source è anche utile, poiché, sebbene documentare ha un costoL'investimento, se fatto correttamente, ne vale la pena. Perché il mondo di Software è pieno di storie su codici legacy di programmi, applicazioni o sistemi vecchi o attuali, che solo poche persone osano toccare, perché quasi nessuno capisce. I programmatori si concentrano sulla creazione di codice e non sulla documentazione corretta e completa. E questo deve essere risolto.

Buone pratiche sulla documentazione nei file di testo README

Nel caso di Software libero e open source, la documentazione è spesso limitata ai file di testo, quando viene creata da individui o piccoli gruppi di programmatori o comunità. Ma, fino a creare una semplice documentazione utilizzando un semplice file file di testo README.md (o .txt) puoi avere il tuo migliori o buone pratiche, suggerimenti o utili guide di creazione per portare a terzi le informazioni più complete e dettagliate necessarie sul creato.

Per il nostro articolo, abbiamo preso il Buone pratiche ideato e divulgato da "Code for Development Initiative" del Banca Interamericana di Sviluppo, che in modo sintetico ci dice che una buona documentazione basata su a file di testo README.md (o .txt) Deve essere strutturato come segue:

Struttura del file README consigliata

• Descrizione e contesto: Sezione in cui è necessario descrivere le funzionalità, il contesto in cui è stato sviluppato e i problemi di sviluppo che ha contribuito a risolvere.
• Guida dell'utente: Sezione in cui devono essere menzionate le istruzioni per l'utente finale su come iniziare a utilizzare lo strumento digitale.
• Guida d'installazione: Sezione in cui devono essere menzionate le istruzioni di installazione per riutilizzare e configurare lo strumento digitale. Questa sezione è destinata agli sviluppatori.
• autori Sezione in cui vanno attribuiti i crediti ai collaboratori dello strumento.
• Licenza per il codice dello strumento: Sezione in cui devono essere specificate le autorizzazioni concesse a terzi per il riutilizzo dello strumento digitale.
• Licenza per la documentazione dello strumento: Sezione in cui deve essere menzionato il tipo di licenza contenuta nella documentazione creata.

In questi buone pratiche, consigliano anche di aggiungere a Documentazione del file README per renderlo più completo, le seguenti sezioni:

• Come contribuire: Sezione che spiega ai nuovi sviluppatori il processo per contribuire ai progetti.
• Codice di condotta: La sezione che spiega il codice di condotta stabilisce le norme sociali, le regole e le responsabilità che gli individui e le organizzazioni devono seguire quando interagiscono in qualsiasi modo con lo strumento digitale o la loro comunità.
• Distintivi: Sezione che mostra i badge (piccole immagini incorporate nel README.md) che specificano in modo leggibile e conciso lo stato dello strumento.
• Versione: Sezione che indica un elenco delle versioni dello strumento digitale e delle funzionalità aggiunte a ciascuna versione.
• Ringraziamenti: Sezione che contiene i riconoscimenti ad altre persone o organizzazioni che hanno contribuito in qualche modo al progetto.

Per espandere queste informazioni, sul Buone pratiche in materia di documentazione per lo sviluppo di software gratuito, dal "Code for Development Initiative" del Banca Interamericana di Sviluppo è possibile fare clic sul seguente collegamento: Documentazione - Guida per la pubblicazione di strumenti digitali. E in altre pubblicazioni esploreremo la parte a cui si fa riferimento buone pratiche su valutazione e licenza del Software gratuito e aperto loro stessi.

Conclusione

Lo speriamo questo "piccolo post utile" su «Buenas prácticas» nel campo di «documentación» creare durante lo sviluppo «Software libre y abierto», è di grande interesse e utilità, per l'intero «Comunidad de Software Libre y Código Abierto» e di grande contributo alla diffusione del meraviglioso, gigantesco e crescente ecosistema di applicazioni di e per «GNU/Linux».

E per ulteriori informazioni, non sempre esitare a visitarne uno Biblioteca in linea come OpenLibra y jedit leggere libri (PDF) su questo o altri argomenti aree di conoscenza. Per ora, se ti è piaciuto «publicación», non smettere di condividerlo con gli altri, nel tuo Siti web, canali, gruppi o comunità preferiti di social network, preferibilmente gratuiti e aperti come Mastodonteo sicuro e privato come Telegram.

O semplicemente visita la nostra home page all'indirizzo DesdeLinux o unisciti al canale ufficiale Telegramma da DesdeLinux leggere e votare questa o altre interessanti pubblicazioni su «Software Libre», «Código Abierto», «GNU/Linux» e altri argomenti relativi a «Informática y la Computación», E il «Actualidad tecnológica».