Labas prakses bezmaksas un atvērtas programmatūras izstrādei: dokumentācija

Dokumentācija: laba prakse bezmaksas un atvērtas programmatūras izstrādei

Dokumentācija: laba prakse bezmaksas un atvērtas programmatūras izstrādei

La Dokumentācija ir un tai vajadzētu būt pamatelementam radošais process un plānošana visu cilvēku darbību un vairāk tehnoloģiskajā jomā, jo īpaši Programmatūras izstrāde.

El visas dokumentācijas mērķis tam jābūt Viņam mācīt trešajām pusēm (lietotājiem, administratoriem, uzturētājiem vai citiem izstrādātājiem), kuri parasti nav pazīstami ar produkts (kods, lietojumprogramma vai sistēma), kā tas tiek izveidots tā struktūra, darbība un pat, ja iespējams, tā izveides iemeslu un tā projektēšanas un darbības veidu.

Laba prakse: dokumentācija - ievads

Turklāt konkrētajā gadījumā Bezmaksas programmatūras dokumentācija ir ļoti svarīga, jo tas ļauj pilnībā garantēt zināšanu nodošana un iespēju nodrošināšana kas vajadzīgi, lai apmierinoši izpildītu 4 brīvības tā ir:

  • 0: Brīvība palaist programmu, kā vēlaties, jebkuram mērķim.
  • 1: Brīvība piekļūt programmai un studēt to, kā arī mainīt vai pielāgot to savā labā.
  • 2: Brīvība kopīgot vai izplatīt kopijas, lai izplatītu to pašu un / vai palīdzētu citiem.
  • 3: Brīvība izplatīt modificēto versiju kopijas trešajām personām.

Laba dokumentācija ļauj tāpēc izveidotajam produktam:

  • To lieto pareizi, un to ir vieglāk iemācīt un iemācīties.
  • Esiet pilnībā saprotams tiem, kas vēlas to pārveidot, lai uzlabotu vai pielāgotu.
  • Esiet dalīts un uzņemts ar lielāku pārliecību visu potenciālo paziņu un svešinieku vidū.
  • Lai sabiedrībā būtu lielāka masa.

Labā prakse: Dokumentācija - Readme

Labā prakse: dokumentācija

Pamati

Šajā gadījumā Bezmaksas programmatūras un atvērtā koda izstrāde, parasti galvenie dokumentācijas lietotāji attiecībā uz produkta dizainu ir tie, kas ir vai būs, atbildīgs par apkopi no tā paša. Un bez labas vai bez dokumentācijas vienīgā reālā alternatīva ir to tieši izpētīt, sasniegt saprast tā dizainu un funkcijas.

Neveido labu dokumentāciju, kad runa ir izstrādāt bezmaksas programmatūru, atvērto avotu vai jebkura cita veida programmatūra ir jānosūta tā iespējamajiem adresātiem (lietotāji, administratori, uzturētāji vai citi izstrādātāji) atrast ceļu cauri džungļiem bez kartes vai kompasa.

Katram izveidojiet labu dokumentāciju Bezmaksas programmatūra, atvērtā koda tas ir arī izdevīgi, jo, lai arī dokumentēšanai ir izmaksasIeguldījums, ja tas izdarīts pareizi, ir tā vērts. Tāpēc, ka programmatūra ir pilns ar stāstiem par mantotie kodi vecas vai pašreizējas programmas, lietojumprogrammas vai sistēmas, kurām tikai daži cilvēki uzdrošinās pieskarties, jo gandrīz neviens to nesaprot. Programmētāji koncentrējas uz koda izveidi, nevis tā pareizu un pilnīgu dokumentēšanu. Un tas ir jānovērš.

Labā prakse attiecībā uz dokumentāciju README teksta failos

Šajā gadījumā Bezmaksas programmatūra un atvērtais kods, dokumentācija bieži aprobežojas ar teksta failiem, ja to izveido personas vai nelielas programmētāju grupas vai kopienas. Bet, līdz izveidojat vienkāršu dokumentāciju, izmantojot vienkāršu teksta fails README.md (vai .txt) jums var būt jūsu labāko vai labo praksi, padomi vai noderīgs radīšanas ceļvedis, lai trešajām personām sniegtu pēc iespējas pilnīgāku un detalizētāku informāciju par izveidoto.

Mūsu rakstam mēs esam izmantojuši Labā prakse ko izdomājusi un atklāj "Attīstības iniciatīvas kods" del Amerikas Attīstības banka, kas kopsavilkumā norāda, ka laba dokumentācija, kuras pamatā ir a teksta fails README.md (vai .txt) Tam jābūt strukturētam šādi:

Ieteicamā README faila struktūra

  • Apraksts un konteksts: Sadaļa, kurā jāapraksta funkcionalitātes, konteksts, kurā tā tika izstrādāta, un attīstības problēmas, kuras tas palīdzēja atrisināt.
  • Lietotāja rokasgrāmata: Sadaļa, kurā jāpiemin instrukcijas galalietotājam par to, kā sākt izmantot digitālo rīku.
  • Uzstādīšanas rokasgrāmata: Sadaļa, kurā jāpiemin instalēšanas instrukcijas digitālā rīka atkārtotai izmantošanai un konfigurēšanai. Šī sadaļa ir paredzēta izstrādātājiem.
  • autori Sadaļa, kurā kredīti jāpiešķir rīka līdzstrādniekiem.
  • Rīka koda licence: Sadaļa, kurā jānorāda trešajām personām piešķirtās atļaujas atkārtoti izmantot digitālo rīku.
  • Rīka dokumentācijas licence: Sadaļa, kurā jānorāda izveidotās dokumentācijas licences tips.

šajās labas prakses, viņi arī iesaka pievienot README faila dokumentācija lai padarītu to pilnīgāku, izmantojiet šādas sadaļas:

  • Kā piedalīties: Sadaļa, kurā jaunajiem izstrādātājiem tiek paskaidrots, kā piedalīties projektos.
  • Rīcības kodekss: Sadaļā, kurā izskaidrots rīcības kodekss, noteiktas sociālās normas, noteikumi un atbildība, kas indivīdiem un organizācijām jāievēro, jebkādā veidā mijiedarbojoties ar digitālo rīku vai viņu kopienu.
  • Nozīmītes: Sadaļa, kurā redzamas nozīmītes (mazie attēli, kas iegulti README.md), kas lasāmā un kodolīgā veidā norāda rīka stāvokli.
  • Versija: Sadaļa, kurā norādīts digitālā rīka versiju saraksts un katrai versijai pievienotās funkcijas.
  • Pateicība: Sadaļa, kas satur atzinību citiem cilvēkiem vai organizācijām, kuras kaut kādā veidā ir piedalījušās projektā.

Lai paplašinātu šo informāciju, vietnē Labā prakse jautājumos par dokumentācija attīstībai Bezmaksas programmatūra, ar "Attīstības iniciatīvas kods" del Amerikas Attīstības banka varat noklikšķināt uz šīs saites: Dokumentācija - rokasgrāmata digitālo rīku publicēšanai. Un citās publikācijās mēs izpētīsim daļu, uz kuru attiecas labas prakses par novērtēšana un licencēšana del Bezmaksas un atvērta programmatūra paši.

Secinājums

Secinājums

Mēs to ceram šis "noderīga maz ziņa" par to «Buenas prácticas» jomā «documentación» radīt, kad attīstās «Software libre y abierto», ir liela interese un lietderība kopumā «Comunidad de Software Libre y Código Abierto» un ir liels ieguldījums brīnišķīgās, gigantiskās un pieaugošās ekosistēmas izplatībā «GNU/Linux».

Lai iegūtu vairāk informācijas, ne vienmēr vilcinieties ar kādu no tiem Tiešsaistes bibliotēkaOpenLibra y jedit Lasīt grāmatas (PDF) par šo tēmu vai citiem zināšanu jomas. Pagaidām, ja jums tas patika «publicación», nepārtrauciet to kopīgot ar citiem, jūsu Izlases vietnes, kanāli, grupas vai kopienas sociālo tīklu, vēlams bezmaksas un atvērtu kā Mastodontsvai droša un privāta Telegram.

Vai vienkārši apmeklējiet mūsu mājas lapu vietnē DesdeLinux vai pievienojieties oficiālajam kanālam Telegramma no DesdeLinux lasīt un balsot par šo vai citām interesantām publikācijām vietnē «Software Libre», «Código Abierto», «GNU/Linux» un citas tēmas, kas saistītas ar «Informática y la Computación», un «Actualidad tecnológica».


Esi pirmais, kas komentārus

Atstājiet savu komentāru

Jūsu e-pasta adrese netiks publicēta. Obligātie lauki ir atzīmēti ar *

*

*

  1. Atbildīgais par datiem: Migels Ángels Gatóns
  2. Datu mērķis: SPAM kontrole, komentāru pārvaldība.
  3. Legitimācija: jūsu piekrišana
  4. Datu paziņošana: Dati netiks paziņoti trešām personām, izņemot juridiskus pienākumus.
  5. Datu glabāšana: datu bāze, ko mitina Occentus Networks (ES)
  6. Tiesības: jebkurā laikā varat ierobežot, atjaunot un dzēst savu informāciju.