Добри практики за развој на слободен и отворен софтвер: Документација

La документација е и треба да биде основен дел од креативен процес и планирање од целата човечка активност, и повеќе во технолошката област, особено во областа на Развој на софтвер.

El намена на целата документација мора да биде Тој предавајте трети страни (корисници, администратори, одржувачи или други развивачи), кои обично не се запознаени со производ (код, апликација или систем), како е создадено нејзината структура, неговото работење па дури и ако е можно, причината за нејзиното создавање и неговиот начин на дизајнирање и работење.

Понатаму, во конкретниот случај на Документацијата за слободен софтвер е од витално значење, бидејќи овозможува целосно гарантирање на трансфер на знаење и зајакнување неопходни за задоволително исполнување на 4 слободи промовирани од него, а тоа се:

• 0: Слобода да ја стартувате програмата како што сакате, за која било цел.
• 1: Слобода да пристапите и проучите програма, и да ја промените или прилагодите во ваша лична корист.
• 2: Слобода да ги споделувате или прераспределувате копиите за да ги ширите истите и / или да им помагате на другите.
• 3: Слобода да дистрибуирате копии од вашите изменети верзии на трети страни.

Добра документација овозможува, според тоа, креираниот производ:

• Правилно се користи, и полесно се учи и учи.
• Да бидат темелно разбрани од оние кои сакаат да го изменат за да го подобрат или прилагодат.
• Бидете споделени и примани со поголема самодоверба, меѓу сите потенцијални познаници и странци.
• Имајте подобра маса кај јавноста.

Добри практики: Документација

Основи

Во случај на Развој на слободен софтвер и со отворен извор, генерално, главни корисници на документацијата поврзани со дизајнот на производот, дали се оние што се или ќе бидат, одговорен за одржување од истиот. И без добра или без документација, единствената одржлива алтернатива е директно да се истражи, да се постигне разберете го неговиот дизајн и функција.

Не создавање добра документација кога станува збор развиваат слободен софтвер, со отворен извор или кој било друг вид на софтвер, треба да се испрати до неговите можни приматели (корисници, администратори, одржувачи или други развивачи) да се најде начин низ џунгла без мапа или компас.

Создадете добра документација за секоја од нив Слободен софтвер, со отворен извор исто така е корисно, бидејќи, иако документирање има ценаИнвестицијата, ако е направена правилно, вреди. Бидејќи, светот на софтвер е полн со приказни за наслови за наследство стари или тековни програми, апликации или системи, кои само малку луѓе се осмелуваат да ги допрат, бидејќи скоро никој не ги разбира. Програмерите се фокусираат на создавање код и не го документираат правилно и целосно. И, ова мора да се санира.

Добри практики за документација во текстуалните датотеки README

Во случај на Слободен софтвер и со отворен извор, документацијата често е ограничена на текстуални датотеки, кога е креирана од поединци или мали групи на програмери или заедници. Но, дури и создавање едноставна документација со употреба на едноставна текстуална датотека README.md (или .txt) можеш да си го имаш твојот најдобри или добри практики, совети или корисен водич за создавање за да им ги донесете на трети страни најкомплетните и детални информации потребни за создавањето.

За нашиот напис, го зедовме Добри практики замислен и обелоденет од "Кодекс за иницијатива за развој" del Меѓуамериканска банка за развој, што резимирано ни кажува дека добрата документација заснована на текстуална датотека README.md (или .txt) Мора да биде структурирана на следниов начин:

Препорачана структура за датотеки README

• Опис и контекст: Дел каде мора да ги опишете функционалностите, контекстот каде што е развиен и развојните проблеми што помогнале да се решат.
• Упатство за корисникот: Дел каде треба да бидат наведени упатствата до крајниот корисник за тоа како да започнете со употреба на дигиталната алатка.
• Водич за инсталација: Дел каде треба да се споменат упатствата за инсталација за повторна употреба и конфигурирање на дигиталната алатка. Овој дел е наменет за програмери.
• автори Дел каде мора да се дадат кредити на соработниците на алатката.
• Лиценца за кодот на алатката: Делот каде што мора да бидат наведени дозволите дадени на трети страни за повторна употреба на дигиталната алатка.
• Лиценца за документација на алатката: Дел каде што мора да се спомене видот на лиценцата содржана во креираната документација.

Во овие добри практики, тие исто така препорачуваат додавање на ПРОЧИТАЈТЕ ја документацијата за датотеката за да биде поцелосно, следниве делови:

• Како да придонесете: Дел кој им го објаснува на новите развивачи на процесот да придонесат за проекти.
• Кодекс на однесување: Делот што го објаснува кодексот на однесување ги утврдува општествените норми, правила и одговорности што поединците и организациите мора да ги следат при комуницирање на кој било начин со дигиталната алатка или нивната заедница.
• Значки: Дел што ги покажува значките (мали слики вградени во README.md) кои на читлив и концизен начин ја одредуваат состојбата на алатката.
• Верзија: Дел кој означува список на верзии на дигиталната алатка и функционалности додадени на секоја верзија.
• Благодарници: Дел кој содржи признанија за други луѓе или организации кои придонеле на некој начин во проектот.

Да ги прошириме овие информации, на Добри практики во прашања од документација за развој на Слободен софтвер, од страна на "Кодекс за иницијатива за развој" del Меѓуамериканска банка за развој можете да кликнете на следниот линк: Документација - Водич за објавување дигитални алатки. И во други публикации ќе го истражиме делот што се однесува добри практики на евалуација и лиценцирање del Слободен и отворен софтвер самите.

Заклучок

Се надеваме дека esta "корисен мал пост" за «Buenas prácticas» во полето на «documentación» да се создаде кога се развива «Software libre y abierto», да биде од голем интерес и корисност, за целата «Comunidad de Software Libre y Código Abierto» и од голем придонес кон дифузијата на прекрасниот, гигантски и растечки еко-систем на апликации на и за «GNU/Linux».

И за повеќе информации, секогаш не двоумете се да посетите која било Интернет библиотека како ОпенЛибра y једит да чита книги (PDF) на оваа тема или други области на знаење. Засега, ако ви се допадна ова «publicación», не престанувај да го споделуваш со другите, во твоето Омилени веб-страници, канали, групи или заедници на социјалните мрежи, по можност бесплатни и отворени како Мастодон, или безбеден и приватен како Телеграма.

Или едноставно посетете ја нашата почетна страница на Од Линукс или придружете се на официјалниот канал Телеграма од DesdeLinux да читаат и да гласаат за оваа или друга интересна публикација на «Software Libre», «Código Abierto», «GNU/Linux» и други теми поврзани со «Informática y la Computación», и на «Actualidad tecnológica».