Przejdź do treści głównej

Kiedy i jak dokumentować nowe technologie

autor(ka): Grzegorz Wolański
2016-12-09, 06:54
użytkownik
Grzegorz Wolański – Informatyk. Lubi rozwiązywać drogie problemy
Nazywam się Grzesiek Wolański, mam za sobą kilkaset godzin dokumentowania nowych technologii, mogę wskazać NGO, które jest zadowolone ze stworzonej przeze mnie dokumentacji i będę Twoim szczwanym przewodnikiem po tym nudnym zagadnieniu, jakim jest dokumentacja. Zapnij pasy.

Dokumentuj późno i wolno

„Działające oprogramowanie ponad obszerną dokumentację” — Manifest zwinnego (ang. agile) rozwijania oprogramowania

Tworzenie nowych technologii i dokumentowanie ich to dwa różne procesy.

Jeśli dokumentujesz nową technologię w trakcie jej powstawania, wiele razy przyjdzie Ci zmieniać dokumentację, wyrzucać jej spore fragmenty do kosza i zarządzać poczuciem zmarnowanego czasu.

Prawdziwą dokumentację warto tworzyć dopiero pod koniec współpracy.

Dokumentowanie późno to mniej trwonienia zasobów i szansa na perspektywę z dystansu. Dystans przy tworzeniu dokumentacji nowych technologii ma natomiast bardzo dużą wartość w postaci ogromnego wpływu na jakość dokumentacji.

Kiedy pracowałem przy niepelnosprawnik.pl, po zrobieniu projektu sam zaprogramowałem wszystko, co wymyśliłem. A potem przyszło mi udokumentować ten program. Czas między tworzeniem technologii, między programowaniem a dokumentowaniem, pozwolił mi spojrzeć na swój własny kod oczami obcej osoby. Nie pamiętałem, co zaprogramowałem 6 miesięcy wcześniej. Ten zabieg z późnym dokumentowaniem pozwolił mi stworzyć dużo lepszej jakości dokumentację niż gdybym pisał ją w trakcie tworzenia technologii dla Niepełnosprawnika.


Pisanie dokumentacji późno doprowadziło także do kilku pozytywnych zmian w samym Niepełnosprawniku. Czas pozwolił mi na dystans. Dystans pozwolił mi na spojrzenie świeżym okiem. Spojrzenie świeżym okiem pozwoliło mi samemu wyłapać sytuacje typu „Czemu to jest tak zaprogramowane? Przecież jest na to prostszy/czytelniejszy/… sposób!”.

Nacisk na jakość, nie szybkość tworzenia dokumentacji pozwolił mi też mądrzej obsługiwać niewygodne sytuacje, które nie ominą i Ciebie w Twoim projekcie. Kiedy udokumentowanie niektórych fragmentów Niepełnosprawnika okazywało się z perspektywy czasu bardzo trudne i mozolne, mogłem być szczery ze sobą i na przykład teraz z Tobą: Jeśli trudno wytłumaczyć, jak działa lub co robi kawałek kodu, to nie jest dobrze napisany kod. W takich sytuacjach w ramach tworzenia dokumentacji przeprogramowywałem fragmenty Niepełnosprawnika – tak, żeby łatwiej było mi je opisać.

Jeżeli ktoś Ci mówi, że w jeden dzień lub – ahoj, ułańska fantazjo! – w jeden wieczór stworzy profesjonalną dokumentację projektu, który trwa dłużej niż, powiedzmy, tydzień, odpowiedz, że nie potrzymasz mu piwa i cenisz sobie profesjonalne podejście do tematu.

* * *

Wykorzystaj Wikipedię

Wiesz, że Wikipedia działa w oparciu o darmowy program? Program, który idealnie nadaje się do dokumentowania nowych technologii w organizacjach pozarządowych.

MediaWiki, program napędzający Wikipedię:

– jest dostępny dla osób nietechnicznych,

– pozwala Tobie (nie tylko programistom, inżynierom, specjalistom) edytować dokumentację,

– umożliwia Ci udostępnienie dokumentacji komukolwiek w organizacji lub poza nią,

– maksymalizuje szanse, że dokumentacja Twojego projektu będzie żywym dokumentem,

– zdejmuje Ci z głowy problemy typu „mam dokumentację na innym komputerze” czy „w mojej wersji pliku tego nie ma!”.

Wreszcie, co nie najmniej ważne, wykorzystanie MediaWiki sprawi, że dokumentacja Twojego projektu będzie wyglądać jak Wikipedia. Jakkolwiek głupiutko by to nie brzmiało, jest w tym coś magicznego. Coś budującego zaufanie i ułatwiającego pisanie. Przetestowałem co najmniej kilkanaście narzędzi do tworzenia dokumentacji nowych technologii i dopiero oprogramowanie Wikipedii dało mi poczucie „to jest to; ufam temu narzędziu; mam poczucie, że mogę skupić się na treści (nie formie) i że wpisane tu słowa nie zginą”.

Szalenie polecam MediaWiki.

* * *

Użyj sprytu przy doborze tematów

Najprawdopodobniej nie masz styczności z dokumentacją nowych technologii zbyt często. Doskonale to rozumiem, trochę nawet zazdroszczę. Dobór tematów do uwzględnienia w dokumentacji może być paraliżujący. Nie pozwolimy temu natomiast przekreślić naszych planów stworzenia kopiącej tyłek dokumentacji, prawda?

Przygotowałem dla Ciebie małą ściągawkę. Jeśli nie wiesz, co powinno znaleźć się w dokumentacji Twojej nowej technologii, przemyśl:

– Co nowa osoba lub firma rozważająca zaangażowanie się w rozwój Twojej nowej technologii powinna wiedzieć, żeby w dwie minuty podjąć wstępną decyzję.

– Jakimi pojęciami, slangiem Ty i Twój zespół posługujecie się w pracy nad technologią, oprogramowaniem. Warto spisać te frazy i opatrzyć definicjami. W pracy nad Niepełnosprawnikiem utarło się np. rozróżnienie na „stary” i „nowy” Niepełnosprawnik, które dla kogoś z zewnątrz jest zupełnie niejasne.

– Co nowa osoba techniczna chcąca rozwijać Twoją technologię musi zrobić, by móc zacząć ją modyfikować przy pomocy swoich narzędzi.

– Jakie wymagania techniczne ma Twoja technologia.

– Na 99% z Twoją technologią są związane pliki lub baza danych. Jaka jest ich struktura? Co można znaleźć w każdym jednym folderze, tabeli bazy danych czy pliku?

– Jakie narzędzia zewnętrzne (open source, komercyjne) są wykorzystywane w Twojej technologii?

– Co i kiedy trzeba robić w ramach utrzymania Twojej technologii?

– Z kim kontaktować się w sprawach związanych z projektem? Tych technicznych i nietechnicznych.

– O jakich niedoskonałościach Twojej technologii wiesz.

– Jakie jest hasło do każdego jednego konta związanego z projektem?

– Jak zrobić trzy najbardziej prawdopodobne rzeczy przy Twojej technologii? W dokumentacji Niepełnosprawnika opisałem m.in. jak wyedytować słownik synonimów wyszukiwarki, jak dodać do serwisu stronę internetową z zawartością edytowalną z poziomu systemu zarządzania treścią oraz jak dodać nowy język do istniejących wersji językowych aplikacji.

Nie musisz wiedzieć czy doprowadzić do opisania wszystkich wymienionych wyżej rzeczy. To tylko lista inspiracji dla Ciebie. Ufam, że pomoże Ci nieco w temacie tej nudnej dokumentacji.

* * *

Nie–zły tekst? Kliknij „Podoba mi się” poniżej.

Nie lubisz pisać komentarzy na stronach internetowych? Napisz na .

* * *

Dziękuję za Twój czas. Uśmiechającej reszty dnia!

* * *

Grzegorz Wolański – Informatyk. Lubi rozwiązywać drogie problemy.


Wiadomość nadesłana przez czytelniczkę/czytelnika portalu www.ngo.pl.

Źródło: Grzegorz Wolański
Uwaga! Przedruk, kopiowanie, skracanie, wykorzystanie tekstów (lub ich fragmentów) publikowanych w portalu www.ngo.pl w innych mediach lub w innych serwisach internetowych wymaga zgody Redakcji portalu!
Wyraź opinię 6 0

Skomentuj

KOMENTARZE

Nie ma żadnych komentarzy

Redakcja www.ngo.pl nie ponosi odpowiedzialności za treść komentarzy

  • nowe technologie