Hyvät käytännöt ilmaisen ja avoimen ohjelmiston kehittämiseksi: Dokumentaatio

La asiakirjat on ja sen pitäisi olla keskeinen osa luova prosessi ja suunnittelu ihmisen toiminnasta ja enemmän tekniikan alalta, erityisesti Ohjelmistokehitys.

El kaiken asiakirjan tarkoitus sen täytyy olla Hän opettaa kolmansille osapuolille (käyttäjät, järjestelmänvalvojat, ylläpitäjät tai muut kehittäjät), jotka eivät yleensä tunne tuote (koodi, sovellus tai järjestelmä), miten se luodaan sen rakenne, toiminta ja jopa mahdollisuuksien mukaan syy sen luomiseen sekä sen suunnittelu- ja toimintatapa.

Lisäksi erityistapauksessa Ilmaisen ohjelmiston dokumentaatio on elintärkeää, koska sen avulla voidaan täysin taata tiedon siirtäminen ja vaikutusmahdollisuuksien lisääminen jotka ovat välttämättömiä 4 vapautta jotka ovat:

• 0: Vapaus käyttää ohjelmaa mihin tahansa tarkoitukseen.
• 1: Vapaus päästä ohjelmaan ja opiskella sitä sekä muuttaa tai mukauttaa sitä omaksi eduksi.
• 2: Vapaus jakaa tai jakaa kopioita levittääksesi samoja ja / tai auttaakseen muita.
• 3: Vapaus jakaa muokattujen versioidesi kopioita kolmansille osapuolille.

Hyvän dokumentaation avulla on siis mahdollista, että luotu tuote:

• Sitä käytetään oikein, ja sitä on helpompi opettaa ja oppia.
• Ne, jotka haluavat muokata sitä parantamaan tai mukauttamaan sitä, ymmärtävät ne perusteellisesti.
• Ole jaettu ja otettu vastaan ​​luottavaisemmin kaikkien mahdollisten tuttavien ja tuntemattomien keskuudessa.
• Parempi massa yleisön keskuudessa.

Hyvät käytännöt: Dokumentaatio

perustukset

Tapauksessa Ilmaisten ohjelmistojen ja avoimen lähdekoodin kehittäminen, yleisesti, asiakirjojen pääkäyttäjät suhteessa tuotesuunnitteluun ovat niitä, jotka ovat tai tulevat olemaan, vastuussa kunnossapidosta samaa. Ja ilman hyviä tai puuttuvia asiakirjoja ainoa toteuttamiskelpoinen vaihtoehto on tutkia niitä suoraan ja saavuttaa ymmärtää sen suunnittelun ja toiminnan.

Ei luoda hyvää dokumentaatiota kehittää vapaita ohjelmistoja, avointa lähdekoodia tai muun tyyppinen ohjelmisto, on lähetettävä mahdollisille vastaanottajille (käyttäjät, järjestelmänvalvojat, ylläpitäjät tai muut kehittäjät) löytää tie viidakon läpi ilman karttaa tai kompassia.

Luo hyvät asiakirjat kullekin Ilmainen ohjelmisto, avoimen lähdekoodin se on myös hyödyllistä, koska vaikka dokumentoinnilla on kustannuksiaJos sijoitus tehdään oikein, se on sen arvoinen. Koska, maailman Tuotteemme on täynnä tarinoita vanhat koodit vanhat tai nykyiset ohjelmat, sovellukset tai järjestelmät, joita vain harvat uskaltavat koskettaa, koska melkein kukaan ei ymmärrä. Ohjelmoijat keskittyvät koodin luomiseen eivätkä dokumentoi sitä oikein ja täydellisesti. Ja tämä on korjattava.

Hyvät käytännöt README-tekstitiedostojen dokumentoinnissa

Tapauksessa Ilmainen ohjelmisto ja avoimen lähdekoodin, dokumentaatio rajoittuu usein tekstitiedostoihin, kun sen luovat henkilöt tai pienet ohjelmoijien ryhmät tai yhteisöt. Mutta jopa yksinkertaisen dokumentaation luominen yksinkertaisella tekstitiedosto README.md (tai .txt) voit saada oman parhaat tai hyvät käytännöt, vinkkejä tai hyödyllistä luomisopasta, jotta kolmansille osapuolille saadaan mahdollisimman täydelliset ja yksityiskohtaiset tiedot luotavasta.

Artikkeliamme varten olemme ottaneet Hyvät käytännöt suunnitellut ja julkistamat "Kehitysaloitteen koodi" ja Kehityspankkia, joka tiivistetysti kertoo meille, että a tekstitiedosto README.md (tai .txt) Sen on oltava rakenteeltaan seuraava:

Suositeltava README-tiedostorakenne

• Kuvaus ja asiayhteys: Luku, jossa toiminnot on kuvattava, konteksti, jossa se on kehitetty, ja kehitysongelmat, jotka se auttoi ratkaisemaan.
• Käyttöopas: Osa, jossa on mainittava ohjeet loppukäyttäjälle digitaalisen työkalun käytön aloittamisesta.
• Asennusohje: Kohta, jossa on mainittava asennusohjeet digitaalisen työkalun uudelleenkäyttöä ja määritystä varten. Tämä osio on tarkoitettu kehittäjille.
• kirjoittajat Osa, jossa hyvitykset on annettava työkalun yhteistyökumppaneille.
• Työkalukoodin lisenssi: Osa, jossa kolmansille osapuolille myönnetyt oikeudet digitaalisen työkalun uudelleenkäyttöön on määritettävä.
• Työkalun dokumentaation lisenssi: Osa, jossa luotujen asiakirjojen sisältämä lisenssityyppi on mainittava.

Näissä hyvät käytännöt, he suosittelevat myös lisäämistä README-tiedoston ohjeet sen täydentämiseksi seuraavat kohdat:

• Kuinka osallistua: Luku, jossa selitetään uusille kehittäjille prosessi osallistua projekteihin.
• Menettelyohje: Kohdassa, joka selittää käytännesäännöt, vahvistetaan sosiaaliset normit, säännöt ja vastuut, joita yksilöiden ja organisaatioiden on noudatettava, kun he ovat vuorovaikutuksessa millään tavalla digitaalisen työkalun tai heidän yhteisönsä kanssa.
• Merkit: Osa, joka näyttää merkit (pienet kuvat upotettuna README.md-tiedostoon), jotka määrittelevät työkalun tilan luettavalla ja ytimekkäällä tavalla.
• Versio: Osa, joka näyttää luettelon digitaalisen työkalun versioista ja kuhunkin versioon lisätyistä toiminnoista.
• Kiitokset: Osa, joka sisältää tunnustukset muille ihmisille tai organisaatioille, jotka ovat osallistuneet jollakin tavalla projektiin.

Laajentaaksesi näitä tietoja, Hyvät käytännöt asioissa dokumentointi kehittämiseen vapaa ohjelmisto, mukaan "Kehitysaloitteen koodi" ja Kehityspankkia voit napsauttaa seuraavaa linkkiä: Dokumentaatio - Opas digitaalisten työkalujen julkaisemiseen. Ja muissa julkaisuissa tutkimme osaa, joka viittaa hyvät käytännöt noin arviointi ja lisensointi ja Ilmainen ja avoin ohjelmisto itse.

Johtopäätös

Toivomme että tämä "hyödyllinen pieni viesti" päälle «Buenas prácticas» alalla «documentación» luoda kehitettäessä «Software libre y abierto», on erittäin kiinnostava ja hyödyllinen kokonaisuudessaan «Comunidad de Software Libre y Código Abierto» ja suurella panoksella ihmeellisen, jättimäisen ja kasvavan ekosysteemin levittämiseen «GNU/Linux».

Ja lisätietoja, älä aina epäröi vierailla missään Verkkokirjasto kuten OpenLibra y jedit lukea kirjat (PDF) aiheesta tai muusta osaamisalueet. Toistaiseksi, jos pidit tästä «publicación», älä lopeta sen jakamista muiden kanssa, sinun Suosikkisivustot, kanavat, ryhmät tai yhteisöt sosiaalisia verkostoja, mieluiten ilmaisia ​​ja avoimia Mastodonttitai turvallinen ja yksityinen Telegram.

Tai yksinkertaisesti käy kotisivullamme osoitteessa DesdeLinux tai liity viralliseen kanavaan Sähke lähettäjältä DesdeLinux lukea ja äänestää tätä tai muita mielenkiintoisia julkaisuja «Software Libre», «Código Abierto», «GNU/Linux» ja muut aiheeseen liittyvät aiheet «Informática y la Computación»Ja «Actualidad tecnológica».