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.
Grzegorz Wolański – Informatyk. Lubi rozwiązywać drogie problemy
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.
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ą”.
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.
Dziękuję za Twój czas. Uśmiechającej reszty dnia!
Grzegorz Wolański – Informatyk. Lubi rozwiązywać drogie problemy.
Źródło: Grzegorz Wolański
