Dobre praktyki tworzenia wolnego i otwartego oprogramowania: dokumentacja

La dokumentacji jest i powinna być podstawową częścią proces twórczy i planowanie wszelkiej działalności człowieka, a nie tylko w dziedzinie technologii, zwłaszcza w dziedzinie Rozwój oprogramowania.

El cel całej dokumentacji to musi być On uczyć osoby trzecie (użytkowników, administratorów, opiekunów lub innych programistów), którzy zwykle nie są zaznajomieni z produkt (kod, aplikacja lub system), jak to jest tworzone jego strukturę, jego działanie a nawet jeśli to możliwe, powód jego powstania oraz sposób projektowania i działania.

Ponadto w konkretnym przypadku Dokumentacja wolnego oprogramowania jest niezbędna, ponieważ pozwala w pełni zagwarantować transfer wiedzy i upodmiotowienie niezbędne do zadowalającego spełnienia wymagań 4 wolności przez nią promowane, którymi są:

• 0: Swoboda uruchamiania programu w dowolny sposób i w dowolnym celu.
• 1: Swoboda dostępu do programu i studiowania go oraz zmiany lub dostosowania go dla własnej korzyści.
• 2: Swoboda dzielenia się lub redystrybucji kopii w celu rozpowszechniania tego samego i / lub pomocy innym.
• 3: Swoboda rozpowszechniania kopii zmodyfikowanych przez Ciebie wersji osobom trzecim.

Dobra dokumentacja umożliwia zatem, że stworzony produkt:

• Jest używany poprawnie i jest łatwiejszy do nauczenia i nauczenia.
• Bądź dobrze zrozumiany przez tych, którzy chcą go zmodyfikować, aby go ulepszyć lub dostosować.
• Bądź dzielony i przyjmowany z większym zaufaniem wśród wszystkich możliwych znajomych i nieznajomych.
• Miej lepszą masę wśród opinii publicznej.

Dobre praktyki: dokumentacja

Podstawy

W przypadku Rozwój wolnego oprogramowania i oprogramowania typu open sourcegeneralnie główni użytkownicy dokumentacji w odniesieniu do projektu produktu, to te, które są lub będą odpowiedzialny za utrzymanie tego samego. Bez dobrej dokumentacji lub bez niej jedyną realną alternatywą jest bezpośrednie zbadanie jej i osiągnięcie zrozumieć jego konstrukcję i funkcję.

Nie tworzy dobrej dokumentacji, jeśli chodzi o rozwijać Wolne Oprogramowanie, Open Source lub innego rodzaju oprogramowanie, ma zostać przesłane do jego ewentualnych odbiorców (użytkownicy, administratorzy, opiekunowie lub inni programiści) znaleźć drogę przez dżunglę bez mapy lub kompasu.

Utwórz dobrą dokumentację dla każdego Wolne oprogramowanie, otwarte oprogramowanie jest to również korzystne, ponieważ chociaż dokumentowanie kosztujeInwestycja, jeśli zostanie wykonana prawidłowo, jest tego warta. Ponieważ świat Tworzenie jest pełen historii starsze kody stare lub aktualne programy, aplikacje lub systemy, których tylko nieliczni mają odwagę dotknąć, ponieważ prawie nikt ich nie rozumie. Programiści skupiają się na tworzeniu kodu, a nie dokumentowaniu go poprawnie i kompletnie. I należy temu zaradzić.

Dobre praktyki dotyczące dokumentacji w plikach tekstowych README

W przypadku Wolne oprogramowanie i otwarte oprogramowaniedokumentacja jest często ograniczona do plików tekstowych, gdy jest tworzona przez pojedyncze osoby lub małe grupy programistów lub społeczności. Ale dopóki nie utworzysz prostej dokumentacji przy użyciu prostego plik tekstowy README.md (lub .txt) możesz mieć swój najlepsze lub dobre praktyki, wskazówki lub przydatny przewodnik po tworzeniu, aby udostępnić stronom trzecim najbardziej kompletne i szczegółowe informacje o dziele.

W naszym artykule wzięliśmy Dobre praktyki wymyślone i ujawnione przez "Kod inicjatywy rozwojowej" del Bank Rozwoju, co w skrócie mówi nam, że dobra dokumentacja oparta na plik tekstowy README.md (lub .txt) Musi mieć następującą strukturę:

Zalecana struktura pliku README

• Opis i kontekst: Sekcja, w której należy opisać funkcjonalności, kontekst, w którym został opracowany oraz problemy programistyczne, które pomogły rozwiązać.
• Poradnik użytkownika: Sekcja, w której należy wspomnieć o instrukcji dla użytkownika końcowego, jak rozpocząć korzystanie z narzędzia cyfrowego.
• Instrukcja instalacji: Sekcja, w której należy wymienić instrukcje instalacji dotyczące ponownego użycia i konfiguracji narzędzia cyfrowego. Ta sekcja jest przeznaczona dla programistów.
• autorzy Sekcja, w której należy przyznać kredyty współpracownikom narzędzia.
• Licencja na kod narzędzia: Sekcja, w której należy określić uprawnienia przyznane stronom trzecim w celu ponownego wykorzystania narzędzia cyfrowego.
• Licencja na dokumentację narzędzia: Sekcja, w której należy wskazać rodzaj licencji zawarty w utworzonej dokumentacji.

W tych dobre praktyki, zalecają również dodanie do Dokumentacja pliku README aby było bardziej kompletne, poniższe sekcje:

• Jak pomóc: Sekcja wyjaśniająca nowym programistom proces wnoszenia wkładu w projekty.
• Kodeks postępowania: Sekcja wyjaśniająca kodeks postępowania ustanawia normy społeczne, zasady i obowiązki, których muszą przestrzegać osoby i organizacje podczas jakiejkolwiek interakcji z narzędziem cyfrowym lub ich społecznością.
• Odznaki: Sekcja przedstawiająca znaczki (małe obrazy osadzone w pliku README.md), które w czytelny i zwięzły sposób określają stan narzędzia.
• Wersja: Sekcja wskazująca listę wersji narzędzia cyfrowego i funkcjonalności dodanych do każdej wersji.
• Podziękowanie: Sekcja zawierająca podziękowania dla innych osób lub organizacji, które w jakiś sposób przyczyniły się do powstania projektu.

Aby rozszerzyć te informacje, w Dobre praktyki w sprawach dokumentacja dla rozwoju wolne oprogramowanie, przez "Kod inicjatywy rozwojowej" del Bank Rozwoju możesz kliknąć poniższy link: Dokumentacja - przewodnik dotyczący publikowania narzędzi cyfrowych. W innych publikacjach zajmiemy się częścią, do której się odwołujemy dobre praktyki na ocena i licencjonowanie del Darmowe i otwarte oprogramowanie sami.

Wnioski

Mamy nadzieję, że esta "pomocny mały post" o «Buenas prácticas» w dziedzinie «documentación» tworzyć podczas programowania «Software libre y abierto», cieszy się dużym zainteresowaniem i użytecznością dla całości «Comunidad de Software Libre y Código Abierto» i ma wielki wkład w rozprzestrzenianie się wspaniałego, gigantycznego i rosnącego ekosystemu zastosowań i dla «GNU/Linux».

Aby uzyskać więcej informacji, nie zawsze wahaj się je odwiedzić Biblioteka online jako OpenLibra y Jedit czytać książki (pliki PDF) na ten temat lub inne obszary wiedzy. Na razie, jeśli to lubisz «publicación», nie przestawaj się tym dzielić z innymi w swoim Ulubione witryny internetowe, kanały, grupy lub społeczności sieci społecznościowych, najlepiej bezpłatnych i otwartych jako Mastodontlub bezpieczne i prywatne jak Telegram.

Lub po prostu odwiedź naszą stronę główną pod adresem DesdeLinux lub dołącz do oficjalnego kanału Telegram z DesdeLinux czytać i głosować na tę lub inne interesujące publikacje «Software Libre», «Código Abierto», «GNU/Linux» i inne tematy związane z «Informática y la Computación»i «Actualidad tecnológica».