Jó gyakorlatok az ingyenes és nyílt szoftver fejlesztéséhez: Dokumentáció

La dokumentáció alapvető része és annak kell lennie a kreatív folyamat és tervezés az emberi tevékenység egésze, és még inkább a technológiai téren, különösen a Szoftverfejlesztés.

El minden dokumentáció célja bizonyára Ő az tanítson harmadik feleket (felhasználók, rendszergazdák, fenntartók vagy más fejlesztők), akik általában nem ismerik a termék (kód, alkalmazás vagy rendszer), hogyan jön létre felépítése, működése és még ha lehetséges is, létrehozásának oka, kialakításának és működésének módja.

Továbbá a Az ingyenes szoftver dokumentációja létfontosságú, mivel lehetővé teszi a tudásátadás és felhatalmazás szükséges a program kielégítő teljesítéséhez 4 szabadság által támogatott, amelyek:

• 0: A program tetszőleges célú futtatásának szabadsága.
• 1: A programhoz való hozzáférés és a tanulmányozás szabadsága, valamint a saját javára történő változtatás vagy adaptálás.
• 2: A másolatok megosztásának vagy terjesztésének szabadsága, hogy ugyanazokat terjessze és / vagy másoknak segítsen.
• 3: A módosított verziók másolatainak harmadik feleknek történő terjesztésének szabadsága.

A megfelelő dokumentáció lehetővé teszi tehát, hogy a létrehozott termék:

• Helyesen használják, és könnyebben megtanulják és megtanulják.
• Alaposan értsék meg azok, akik módosítani szeretnék, hogy javítsák vagy adaptálják.
• Legyen megosztottabb és fogadjon nagyobb bizalommal minden potenciális ismerős és idegen között.
• Legyen nagyobb tömeg a nyilvánosság körében.

Jó gyakorlatok: Dokumentáció

Alapismeretek

Abban az esetben, Ingyenes szoftver és nyílt forráskódú fejlesztésáltalában a dokumentáció fő felhasználói a termék tervezéséhez képest azok, amelyek vannak vagy lesznek, a felelős a karbantartásért ugyanabból. Jó vagy hiányos dokumentáció nélkül az egyetlen életképes alternatíva az, hogy közvetlenül feltárja, elérje megérteni annak kialakítását és működését.

Nem készít jó dokumentációt, amikor arról van szó szabad szoftver, nyílt forráskódú fejlesztése vagy bármilyen más típusú szoftvert kell elküldeni a lehetséges címzetteknek (felhasználók, rendszergazdák, karbantartók vagy más fejlesztők) térkép vagy iránytű nélkül utat találni egy dzsungelben.

Készítsen jó dokumentációt mindegyikhez Ingyenes szoftver, nyílt forráskód előnyös is, hiszen bár a dokumentálás költségekkel járA befektetés, ha helyesen történik, megéri. Mert, a világ szoftver tele van történetekkel arról örökölt kódok régi vagy jelenlegi programok, alkalmazások vagy rendszerek, amelyekhez csak kevesen mernek hozzáérni, mert szinte senki sem érti. A programozók a kód létrehozására összpontosítanak, és nem dokumentálják helyesen és teljesen. És ezt orvosolni kell.

A README szövegfájlok dokumentálásával kapcsolatos bevált gyakorlatok

Abban az esetben, Ingyenes szoftver és nyílt forráskód, a dokumentáció gyakran csak szöveges fájlokra korlátozódik, amikor azokat egyének, vagy programozók vagy csoportok kis csoportjai vagy közösségek hozzák létre. De amíg nem készít egy egyszerű dokumentációt egy egyszerű használatával szövegfájl README.md (vagy .txt) megkaphatja a legjobb vagy jó gyakorlatok, tippek vagy hasznos útmutató az alkotásról, hogy harmadik feleknek eljuttassa a létrehozottról szükséges legteljesebb és legrészletesebb információkat.

Cikkünkhöz a Jó gyakorlatok által kitalált és nyilvánosságra hozott "Fejlesztési Kezdeményezés kódja" del Amerikai Fejlesztési Bank, amely összefoglalóan elmondja, hogy a jó dokumentáció a szövegfájl README.md (vagy .txt) A következőképpen kell felépíteni:

Ajánlott README fájlstruktúra

• Leírás és kontextus: Szakasz, ahol le kell írni a funkcionalitásokat, a kontextust, ahol kidolgozták, és a fejlesztési problémákat, amelyek megoldását segítette.
• Felhasználói Útmutató: Az a szakasz, ahol meg kell említeni a végfelhasználónak a digitális eszköz használatának megkezdésével kapcsolatos utasításokat.
• Telepítési útmutató: Az a szakasz, ahol meg kell említeni a digitális eszköz újrafelhasználására és konfigurálására vonatkozó telepítési utasításokat. Ez a szakasz fejlesztőknek szól.
• szerzők Szakasz, ahol kreditet kell adni az eszköz munkatársainak.
• Szerszámkód licenc: Szakaszt, ahol meg kell adni a harmadik félnek a digitális eszköz újrafelhasználására adott engedélyeket.
• Szerszámdokumentáció licenc: Szakasz, ahol meg kell említeni a létrehozott dokumentációban szereplő engedély típusát.

ezekben jó gyakorlatok, javasolják a A README fájl dokumentációja teljesebbé tétele érdekében a következő szakaszokat:

• Hogyan járulhat hozzá: Szakasz, amely elmagyarázza az új fejlesztőknek a projektekhez való hozzájárulás folyamatát.
• Magatartási kódex: A magatartási kódexet elmagyarázó szakasz meghatározza azokat a társadalmi normákat, szabályokat és felelősségeket, amelyeket az egyéneknek és szervezeteknek be kell tartaniuk, ha bármilyen módon érintkeznek a digitális eszközzel vagy közösségükkel.
• Jelvények: A jelvényeket (a README.md-be ágyazott kis képeket) bemutató szakasz, amely olvashatóan és tömören meghatározza az eszköz állapotát.
• Változat: Szakasz, amely a digitális eszköz verzióinak listáját és az egyes változatokhoz hozzáadott funkciókat tartalmazza.
• Köszönetnyilvánítás: Szekció, amely elismeréseket tartalmaz a projekthez valamilyen módon hozzájáruló más emberek vagy szervezetek számára.

Ezen információk bővítéséhez a Jó gyakorlatok ügyekben Dokumentáció fejlesztésére ingyenes szoftver, valami által "Fejlesztési Kezdeményezés kódja" del Amerikai Fejlesztési Bank kattintson a következő linkre: Dokumentáció - Útmutató a digitális eszközök közzétételéhez. Más publikációkban pedig feltárjuk a hivatkozó részt jó gyakorlatok on értékelés és engedélyezés del Ingyenes és nyílt szoftver maguk.

Következtetés

Reméljük ezt "hasznos kis bejegyzés" tovább «Buenas prácticas» területén «documentación» a fejlesztés során létrehozni «Software libre y abierto», egészében nagy érdeklődés és hasznosság «Comunidad de Software Libre y Código Abierto» és nagyban hozzájárul a csodálatos, gigantikus és egyre növekvő ökoszisztéma elterjedéséhez a «GNU/Linux».

És további információért ne habozzon, látogasson meg bármelyiket Online könyvtár mint OpenLibra y jEdit olvasni könyvek (PDF) erről a témáról vagy másokról tudásterületek. Egyelőre, ha ez tetszett «publicación», ne hagyd abba a megosztást másokkal, a te Kedvenc webhelyek, csatornák, csoportok vagy közösségek közösségi hálózatok, lehetőleg ingyenesek és nyitottak Masztodon, vagy biztonságos és privát Telegram.

Vagy egyszerűen keresse fel honlapunkat: DesdeLinux vagy csatlakozzon a hivatalos csatornához Távirata DesdeLinux olvasni és szavazni erre vagy más érdekes kiadványokra «Software Libre», «Código Abierto», «GNU/Linux» és egyéb kapcsolódó témák «Informática y la Computación»és a «Actualidad tecnológica».