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

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

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

La документация е и трябва да бъде основна част от творчески процес и планиране от цялата човешка дейност и повече в технологичната област, особено в областта на Разработване на софтуер.

El предназначение на цялата документация трябва да е Той да преподава на трети страни (потребители, администратори, поддържащи или други разработчици), които обикновено не са запознати с продукт (код, приложение или система), как се създава неговата структура, нейното функциониране и дори ако е възможно, причината за създаването му и начина му на проектиране и работа.

Добри практики: Документация - Въведение

Освен това, в конкретния случай на Документацията за свободния софтуер е жизненоважна, тъй като позволява напълно да се гарантира трансфер на знания и овластяване необходими за задоволителното изпълнение на 4 свободи насърчавани от него, които са:

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

Следователно добрата документация позволява създаденият продукт:

  • Използва се правилно и по-лесно се преподава и учи.
  • Бъдете добре разбрани от тези, които желаят да го модифицират, за да го подобрят или адаптират.
  • Бъдете споделени и приети с повече увереност, сред всички потенциални познати и непознати.
  • Имайте по-добра маса сред обществеността.

Добри практики: Документация - Readme

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

Основни положения

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

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

Създайте добра документация за всеки Свободен софтуер, отворен код това също е от полза, тъй като, въпреки че документирането има ценаИнвестицията, ако е направена правилно, си заслужава. Защото светът на Софтуер е пълен с истории за наследствени кодове стари или актуални програми, приложения или системи, до които само малко хора се осмеляват да се докоснат, защото почти никой не разбира. Програмистите се фокусират върху създаването на код и не го документират правилно и изцяло. И това трябва да бъде отстранено.

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

В случай на Безплатен софтуер и отворен код, документацията често е ограничена до текстови файлове, когато е създадена от лица или малки групи програмисти или общности. Но до създаването на проста документация с помощта на проста текстов файл README.md (или .txt) можете да получите своя най-добри или добри практики, съвети или полезно ръководство за създаване, за да предоставите на трети страни най-пълната и подробна информация, необходима за създаденото.

За нашата статия взехме Най-добри практики замислена и разкрита от "Кодекс за инициатива за развитие" дел Bank Интерамерикан развитие, което в обобщение ни казва, че добрата документация, базирана на a текстов файл README.md (или .txt) Тя трябва да бъде структурирана по следния начин:

Препоръчителна файлова структура README

  • Описание и контекст: Раздел, в който трябва да бъдат описани функционалностите, контекстът, в който е разработен, и проблемите за развитие, които е помогнал да се решат.
  • Ръководство на потребителя: Раздел, в който трябва да се споменат инструкции до крайния потребител как да започне да използва цифровия инструмент.
  • Ръководство за инсталиране: Раздел, в който трябва да се споменат инструкциите за инсталиране за повторно използване и конфигуриране на цифровия инструмент. Този раздел е предназначен за разработчици.
  • автори Раздел, в който трябва да се дадат кредити на сътрудниците на инструмента.
  • Лиценз за кода на инструмента: Раздел, в който трябва да бъдат посочени разрешенията, предоставени на трети страни за повторно използване на цифровия инструмент.
  • Лиценз за документацията на инструмента: Раздел, в който трябва да се посочи видът на лиценза, съдържащ се в създадената документация.

В тези добри практики, те също препоръчват добавяне към README файлова документация за да бъде по-пълно, следните раздели:

  • Как да допринесете: Раздел, който обяснява на новите разработчици процеса за принос към проекти.
  • Кодекс на поведение: Раздел, който обяснява кодекса за поведение, установява социалните норми, правила и отговорности, които хората и организациите трябва да следват, когато взаимодействат по какъвто и да е начин с цифровия инструмент или тяхната общност.
  • Значки: Раздел, показващ значките (малки изображения, вградени в README.md), които уточняват по четлив и кратък начин състоянието на инструмента.
  • Версия: Раздел, който посочва списък с версиите на цифровия инструмент и функционалностите, добавени към всяка версия.
  • Благодарности: Раздел, който съдържа признателността към други хора или организации, които са допринесли по някакъв начин за проекта.

За да разширите тази информация, на Най-добри практики по въпроси на документация за развитието на Безплатен софтуер, по "Кодекс за инициатива за развитие" дел Bank Интерамерикан развитие можете да кликнете върху следната връзка: Документация - Ръководство за публикуване на цифрови инструменти. И в други публикации ще разгледаме частта, отнасяща се до добри практики на оценка и лицензиране дел Безплатен и отворен софтуер себе си.

Заключение

Заключение

Надяваме се това "полезен малък пост" за «Buenas prácticas» в областта на «documentación» да създава, когато се развива «Software libre y abierto», представляват голям интерес и полезност за цялото «Comunidad de Software Libre y Código Abierto» и от голям принос за разпространението на прекрасната, гигантска и растяща екосистема от приложения на и за «GNU/Linux».

И за повече информация, не винаги се колебайте да посетите някоя Онлайн библиотека като OpenLibra y едит чета книги (PDF файлове) по тази тема или други области на знанието. Засега, ако това ви е харесало «publicación», не спирайте да го споделяте с други, във вашия Любими уебсайтове, канали, групи или общности на социалните мрежи, за предпочитане безплатни и отворени като Мастодон, или сигурно и лично като Telegram.

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


Бъдете първите, които коментират

Оставете вашия коментар

Вашият имейл адрес няма да бъде публикуван. Задължителните полета са отбелязани с *

*

*

  1. Отговорен за данните: Мигел Анхел Гатон
  2. Предназначение на данните: Контрол на СПАМ, управление на коментари.
  3. Легитимация: Вашето съгласие
  4. Съобщаване на данните: Данните няма да бъдат съобщени на трети страни, освен по законово задължение.
  5. Съхранение на данни: База данни, хоствана от Occentus Networks (ЕС)
  6. Права: По всяко време можете да ограничите, възстановите и изтриете информацията си.