Gutt Praktiken fir gratis an oppen Software z'entwéckelen: Dokumentatioun

Dokumentatioun: Gutt Praktiken fir gratis an oppen Software z'entwéckelen

Dokumentatioun: Gutt Praktiken fir gratis an oppen Software z'entwéckelen

La Dokumentatioun ass a soll e fundamentalen Deel vun der kreative Prozess a Planung vun all mënschlecher Aktivitéit, a méi am technologesche Beräich, besonnesch am Beräich vun Software Entwécklung.

El Zweck vun all Dokumentatioun et muss Hien sinn Drëtt Parteien léieren (Benotzer, Administrateuren, Ënnerhalter oder aner Entwéckler), déi normalerweis net mat der Produkt (Code, Uwendung oder System), wéi gëtt et erstallt seng Struktur, seng Operatioun an och wann et méiglech ass, de Grond fir seng Kreatioun a säi Wee fir Design a Betrib.

Gutt Praktiken: Dokumentatioun - Aféierung

Weider, am spezifesche Fall vun Gratis Software Dokumentatioun ass vital, well et erlaabt déi voll ze garantéieren Wëssen iwwerdroen an Ermächtegung néideg fir déi zefriddestellend Erfëllung vun der 4 Fräiheeten gefördert ginn, déi sinn:

  • 0: D'Fräiheet fir de Programm ze maachen wéi Dir wëllt, fir all Zweck.
  • 1: D'Fräiheet fir Zougang zu engem Programm ze studéieren, an z'änneren oder unzepassen fir Ären eegene Benefice.
  • 2: D'Fräiheet Kopien ze deelen oder nei ze verdeelen fir datselwecht ze verbreeden an / oder aneren ze hëllefen.
  • 3: D'Fräiheet Kopie vun Äre modifizéierte Versiounen un Drëttubidder ze verdeelen.

Eng gutt Dokumentatioun mécht et méiglech, datt dat erstallt Produkt:

  • Et gëtt korrekt benotzt, an et gëtt méi einfach geléiert a geléiert.
  • Gitt grëndlech verstanen vun deenen, déi et ännere wëllen, fir se ze verbesseren oder z'adaptéieren.
  • Gitt gedeelt a kritt mat méi Vertrauen, ënner alle potenziellen Bekannten an Auslänner.
  • Hunn eng besser Mass ënner de Public.

Gutt Praktiken: Dokumentatioun - Readme

Gutt Praktiken: Dokumentatioun

Grondsätz

Am Fall vun Entwécklung vu Gratis Software an Open Source, allgemeng, Haaptbenotzer vun der Dokumentatioun bezunn op Produktdesign, sinn déi, déi sinn oder wäerte sinn, déi verantwortlech fir den Ënnerhalt vun der selwechter. An ouni gutt oder keng Dokumentatioun ass déi eenzeg liewensfäeg Alternativ et direkt ze entdecken, z'erreechen säin Design a seng Funktioun verstoen.

Schafe keng gutt Dokumentatioun wann et drëm geet entwéckelen Free Software, Open Source oder all aner Software, soll u méiglech Empfänger geschéckt ginn (Benotzer, Administrateuren, Ënnerhalter oder aner Entwéckler) fir e Wee duerch en Dschungel ze fannen ouni eng Kaart oder e Kompass.

Schafen gutt Dokumentatioun fir all Gratis Software, Open Source et ass och gutt, well awer dokumentéieren huet eng KäschteD'Investitioun, wann et richteg gemaach gëtt, ass et wäert. Well, d'Welt vun Software ass voller Geschichten iwwer Legacy Coden vun alen oder aktuelle Programmer, Uwendungen oder Systemer, déi nëmme wéineg Leit sech trauen ze beréieren, well bal kee versteet. Programméierer konzentréiere sech op Code erstellen an net korrekt a komplett dokumentéieren. An dëst muss behuewe ginn.

Gutt Praktiken iwwer Dokumentatioun an README Textdateien

Am Fall vun Gratis Software an Open Source, Dokumentatioun ass dacks limitéiert op Textdateien, wa se vu Persounen oder klenge Gruppe vu Programméierer oder Gemeinschaften erstallt gëtt. Awer och eng einfach Dokumentatioun mat engem einfachen ze kreéieren Textdatei README.md (oder .txt) Dir kënnt Är bescht oder gutt Praktiken, Tipps oder nëtzlech Kreatiounsguide fir déi drëtt Parteien déi komplettsten an detailléiertsten Informatiounen iwwer déi erstallt ze huelen.

Fir eisen Artikel hu mir den Gutt Praktiken konzipéiert a verëffentlecht vun der "Code fir Entwécklungsinitiativ" vun der Inter-American Development Bank, déi op eng zesummefaassend Manéier eis seet, datt gutt Dokumentatioun baséiert op a Textdatei README.md (oder .txt) Et muss esou strukturéiert sinn:

Recommandéiert README Dateistruktur

  • Beschreiwung a Kontext: Sektioun wou Dir d'Funktionalitéite beschreiwe musst, de Kontext wou et entwéckelt gouf an d'Entwécklungsproblemer déi et gehollef huet ze léisen.
  • Benotzerguide: Sektioun wou d'Instruktioune fir den Endbenutzer wéi een den digitale Tool benotze soll ernimmt ginn.
  • Installatioun Guide: Sektioun wou d'Installatiounsinstruktiounen fir den digitale Tool ze benotzen an ze konfiguréieren sollt ernimmt ginn. Dës Sektioun ass fir Entwéckler geduecht.
  • Auteuren Sektioun wou Kreditter mussen un d'Kollaborateure vum Tool ginn.
  • Lizenz fir den Toolcode: Sektioun wou d'Autorisatiounen déi Drëtt Parteie kréien fir den digitale Tool weiderbenotzen mussen uginn.
  • Lizenz fir d'Dokumentatioun vum Tool: Sektioun wou d'Zort Lizenz an der erstallter Dokumentatioun enthale muss ernimmt ginn.

An dësen gutt Praktiken, si recommandéieren och derbäi ze bäidroen README Dateidokumentatioun fir et méi komplett ze maachen, déi folgend Sektiounen:

  • Wéi bäidroe kann: Sektioun déi den neien Entwéckler de Prozess erkläert fir zu Projete bäizedroen.
  • Behuelungskodex: Sektioun déi de Verhalenskodex erkläert etabléiert d'sozial Normen, Regelen a Verantwortung déi eenzel Persounen an Organisatiounen musse verfollegen wann se iergendwéi mam digitale Tool oder hirer Gemeinschaft interagéieren.
  • Schëlder: Sektioun déi d'Badges weist (kleng Biller an der README.md agebett) déi op eng liesbar a präzis Manéier de Staat vum Tool spezifizéieren.
  • Versioun: Sektioun déi eng Lëscht vun de Versioune vum digitale Tool an d'Funktionalitéiten un all Versioun bezeechent.
  • Unerkennungen: Sektioun déi d'Unerkennunge fir aner Leit oder Organisatiounen enthält déi op eng gewësse Manéier zum Projet bäigedroen hunn.

Fir dës Informatioun auszebauen, op der Gutt Praktiken a Saache vun Dokumentatioun fir d'Entwécklung vu Free Software, vun der "Code fir Entwécklungsinitiativ" vun der Inter-American Development Bank Dir kënnt op dëse Link klickt: Dokumentatioun - Guide fir d'Verëffentlechung vun digitalen Tools. An an anere Publikatioune wäerte mir deen Deel erfuerschen, deen op de gutt Praktiken op der Evaluatioun a Lizenzéierung vun der Gratis an Open Software sech selwer.

Konklusioun

Konklusioun

Mir hoffen dat dat "hëllefräich klenge Post" iwwer «Buenas prácticas» am Feld vun «documentación» ze kreéieren wann Dir entwéckelt «Software libre y abierto», si vu groussem Intérêt an Utilitéit, fir dat Ganzt «Comunidad de Software Libre y Código Abierto» a vu grousse Bäitrag zur Diffusioun vum wonnerschéinen, giganteschen a wuessenden Ökosystem vun Uwendungen vun a fir «GNU/Linux».

A fir méi Informatioun zéckt net ëmmer all ze besichen Online Bibliothéik wéi OpenLibra y JedIT liesen Bicher (PDFs) iwwer dëst Thema oder anerer Wëssen Beräicher. Fir elo, wann Dir dëst gär hätt «publicación», net ophalen et ze deelen mat aneren, an Ärem Liiblingswebsäiten, Kanäl, Gruppen oder Gemeinschaften vu sozialen Netzwierker, am beschten gratis an oppen als Mastodon, oder sécher a privat wéi Hëllefe profitéieren.

Oder besicht einfach eis Homepage um FromLinux oder maach mat beim offiziellen Channel Telegramm vu FromLinux fir dës oder aner interessant Publikatiounen ze liesen an ofzestëmmen «Software Libre», «Código Abierto», «GNU/Linux» an aner Themen am Zesummenhang mat «Informática y la Computación», an der «Actualidad tecnológica».


Den Inhalt vum Artikel hält sech un eis Prinzipie vun redaktionnell Ethik. Fir e Feeler ze mellen klickt hei.

Gitt d'éischt fir ze kommentéieren

Gitt Äre Kommentar

Är Email Adress gëtt net publizéiert ginn. Néideg Felder sinn markéiert mat *

*

*

  1. Responsabel fir d'Daten: Miguel Ángel Gatón
  2. Zweck vun den Donnéeën: Kontroll SPAM, Kommentarmanagement.
  3. Legitimatioun: Är Zoustëmmung
  4. Kommunikatioun vun den Donnéeën: D'Donnéeë ginn net un Drëttubidder matgedeelt ausser duerch legal Verpflichtung.
  5. Datenspeicher: Datebank gehost vun Occentus Networks (EU)
  6. Rechter: Zu all Moment kënnt Dir Är Informatioun limitéieren, recuperéieren an läschen.