God praksis for å utvikle gratis og åpen programvare: dokumentasjon

La dokumentasjon er og bør være en grunnleggende del av kreativ prosess og planlegging av all menneskelig aktivitet, og mer på det teknologiske området, spesielt i området Programvare utvikling.

El formålet med all dokumentasjon det må være ham undervise tredjeparter (brukere, administratorer, vedlikeholdere eller andre utviklere), som vanligvis ikke er kjent med produkt (kode, applikasjon eller system), hvordan er det opprettet dens struktur, dens drift og selv om mulig, årsaken til opprettelsen og dens måte å designe og bruke på.

Videre, i det spesifikke tilfellet av Gratis programvaredokumentasjon er viktig, siden det gjør det mulig å garantere kunnskapsoverføring og empowerment nødvendig for tilfredsstillende oppfyllelse av 4 friheter fremmet av det, som er:

• 0: Friheten til å kjøre programmet uansett hva du vil, for ethvert formål.
• 1: Friheten til å få tilgang til og studere et program, og endre eller tilpasse det til din egen fordel.
• 2: Friheten til å dele eller omfordele kopier for å spre det samme og / eller hjelpe andre.
• 3: Friheten til å distribuere kopier av dine modifiserte versjoner til tredjeparter.

En god dokumentasjon gjør det derfor mulig at det opprettede produktet:

• Den brukes riktig, og den læres lettere og læres lettere.
• Bli grundig forstått av de som ønsker å modifisere den for å forbedre eller tilpasse den.
• Bli delt og mottatt med mer selvtillit, blant alle mulige bekjente og fremmede.
• Ha en bedre masse blant publikum.

God praksis: Dokumentasjon

Grunnleggende

I tilfelle av Utvikling av fri programvare og åpen kildekode, som regel, hovedbrukerne av dokumentasjonen i forhold til produktdesign, er de som er eller vil være, ansvarlig for vedlikehold av det samme. Og uten god eller ingen dokumentasjon, er det eneste levedyktige alternativet å utforske det direkte, å oppnå forstå dens design og funksjon.

Skaper ikke god dokumentasjon når det gjelder utvikle fri programvare, åpen kildekode eller annen type programvare, skal sendes til mulige mottakere (brukere, administratorer, vedlikeholdere eller andre utviklere) for å finne en vei gjennom en jungel uten kart eller kompass.

Lag god dokumentasjon for hver Gratis programvare, åpen kildekode det er også gunstig, siden, skjønt å dokumentere har en kostnadInvesteringen, hvis den gjøres riktig, er verdt det. Fordi, verden av Software er full av historier om eldre koder gamle eller nåværende programmer, applikasjoner eller systemer, som bare få mennesker tør å ta på, fordi nesten ingen forstår. Programmører fokuserer på å lage kode og ikke dokumentere den riktig og fullstendig. Og dette må avhjelpes.

God praksis for dokumentasjon i README tekstfiler

I tilfelle av Gratis programvare og åpen kildekode, er dokumentasjon ofte begrenset til tekstfiler når den er opprettet av enkeltpersoner eller små grupper av programmerere eller lokalsamfunn. Men til du lager en enkel dokumentasjon ved hjelp av en enkel tekstfil README.md (eller .txt) du kan få din beste eller gode fremgangsmåter, tips eller nyttig veiledningsveiledning for å bringe tredjeparter den mest komplette og detaljerte informasjonen som er nødvendig om det som er opprettet.

For vår artikkel har vi tatt Best Practices unnfanget og avslørt av "Kode for utviklingsinitiativ" den Den interamerikanske utviklingsbanken, som i sammendrag forteller oss at god dokumentasjon basert på en tekstfil README.md (eller .txt) Den må være strukturert slik:

Anbefalt README filstruktur

• Beskrivelse og kontekst: Avsnitt der du må beskrive funksjonalitetene, konteksten der den ble utviklet og utviklingsproblemene den hjalp til med å løse.
• Brukermanual: Avsnitt der instruksjoner til sluttbruker om hvordan du begynner å bruke det digitale verktøyet bør nevnes.
• Installasjonsveiledning: Avsnitt der installasjonsinstruksjonene for gjenbruk og konfigurering av det digitale verktøyet bør nevnes. Denne delen er ment for utviklere.
• forfattere Avsnitt der studiepoeng må gis til samarbeidspartnerne av verktøyet.
• Lisens for verktøykoden: Avsnitt der tillatelser gitt til tredjeparter til å gjenbruke det digitale verktøyet må spesifiseres.
• Lisens for verktøydokumentasjonen: Avsnitt der lisenstypen i dokumentasjonen som er opprettet, må nevnes.

I disse god praksis, de anbefaler også å legge til i README-fildokumentasjon for å gjøre det mer komplett, følgende seksjoner:

• Hvordan bidra: Seksjon som forklarer nye utviklere prosessen for å bidra til prosjekter.
• Etiske retningslinjer: Avsnitt som forklarer atferdskoden etablerer de sosiale normene, reglene og ansvaret som enkeltpersoner og organisasjoner må følge når de på noen måte samhandler med det digitale verktøyet eller deres samfunn.
• Merker: Seksjon som viser merkene (små bilder innebygd i README.md) som på en lesbar og kortfattet måte angir verktøyets tilstand.
• Versjon: Avsnitt som viser en liste over versjonene av det digitale verktøyet og funksjonene som er lagt til hver versjon.
• Anerkjennelser: Seksjon som inneholder anerkjennelser til andre mennesker eller organisasjoner som har bidratt på en eller annen måte til prosjektet.

For å utvide denne informasjonen, på Best Practices i spørsmål om dokumentasjon for utvikling av Free Software, ved "Kode for utviklingsinitiativ" den Den interamerikanske utviklingsbanken du kan klikke på følgende lenke: Dokumentasjon - Veiledning for publisering av digitale verktøy. Og i andre publikasjoner vil vi utforske den delen det refererer til god praksis på evaluering og lisensiering den Gratis og åpen programvare dem selv.

Konklusjon

Vi håper det dette "nyttig lite innlegg" på «Buenas prácticas» innen «documentación» å skape når man utvikler seg «Software libre y abierto», være av stor interesse og nytte, for hele «Comunidad de Software Libre y Código Abierto» og med stort bidrag til spredningen av det fantastiske, gigantiske og voksende økosystemet med applikasjoner for og for «GNU/Linux».

Og for mer informasjon, ikke nøl med å besøke noen Nettbibliotek som OpenLibra y jedit å lese bøker (PDF-filer) om dette emnet eller andre kunnskapsområder. For nå, hvis du likte dette «publicación», ikke slutte å dele den med andre, i din Favorittnettsteder, kanaler, grupper eller lokalsamfunn av sosiale nettverk, helst gratis og åpent som Мастодон, eller sikker og privat som Telegram.

Eller bare besøk hjemmesiden vår på DesdeLinux eller bli med på den offisielle kanalen Telegram av DesdeLinux å lese og stemme på denne eller andre interessante publikasjoner på «Software Libre», «Código Abierto», «GNU/Linux» og andre emner relatert til «Informática y la Computación», og «Actualidad tecnológica».