Dokumentacja w ilustracjach

Dokumentacja w ilustracjach

Dzisiaj chciałbym przyznać się do swoich błędów jako programista.
22 maj 2017 2277
Dzisiaj chciałbym przyznać się do swoich błędów jako programista.

Leniwy ze mnie projektant. 
Nie lubię tracić czasu na długotrwałe debugowanie.
Nie lubię wymyślać żadnych integracyjnych hacków. Jestem zbyt leniwy, by używać czasowych rozwiązań, ponieważ później i tak wszystko trzeba będzie przerabiać.
Nie lubię tracić czasu na wyjaśnianie programistom różnych platform architektury tego samego komponentu biznesowego.

Jestem typem wzrokowca, lecz nie umiem ładnie rysować.
Wolę pochłaniać informacje z ilustracji, niż czytać tylko kawałki tekstu. Nie jestem zbyt dobry w rysowaniu od ręki, za to jestem zbyt leniwy, by instalować i używać skomplikowanych narzędzi.

Jestem staroświecki i nudny.
Lubię stare i sprawdzone narzędzia. Lubię dokładność i jednoznaczność, ponieważ jestem zbyt leniwy, by orientować się w niepewności. I jeszcze bardzo lubię, gdy zmiany w dokumentacji mogą być dostatecznie łatwo śledzone.

Tym sposobem, w procesie produkcji i pod wpływem moich wyżej opisanych spostrzeżeń doszedłem do wniosku, że najlepiej tworzyć dokumentację oraz rozpowszechniać ją między programistami, project/product managerami i wydziałem jakości w formie zasobów graficznych.

Wybawienie.

Błądząc w Internecie w poszukiwaniu rozwiązania mojego problemu, przyszedł mi na pomoc Graphviz i DOT. Z pomocą języka DOT można z łatwością opisać diagramy i schematy, które będą odzwierciedlać architekturę jednakowych komponentów dla web, iOS i Androida oraz renderować je w dowolny format - png/svg/jpeg. Istnieje ogromna ilość pluginów dla DOT: pod IDE, serwisy webowe w rodzaju Confluence. Oznacza to, że wizualizacja dokumentu jest możliwa nie tylko z command line'a, lecz także wewnątrz standardowych aplikacji.

Oprócz tego, DOT nadaje się do opisania automatów skończonych => wyeliminowania niepewności i potrzeby domyślania się. No i oczywiście, jako że DOT to swego rodzaju język, fiksacja zmian w pliku tekstowym, posiadającym opis komponenty z pomocą dowolnego systemu kontroli wersji będzie automatycznie zrealizowana.

Patrz niżej, co można robić przy pomocy DOT i Graphviz.

Documentation in Pictures.jpg


A oto reprezentacja tekstowa:

Documentation in Pictures_2.png


Dane podejście bardzo często pomagało mi zarówno w programowaniu, jak i w przeprowadzeniu prezentacji. Przy użyciu tego instrumentu w bardzo szybki i łatwy sposób udawało mi się odzwierciedlić diagram/schemat oraz wnieść wymagane zmiany. Język DOT jest raczej prosty i łatwo go oswoić.

Najbardziej podoba mi się to, że najpierw można skoncentrować się na treści, a nie na przedstawieniu informacji - wszystkie elementy graficzne będą automatycznie narysowane i zorganizowane i nie będzie potrzeby ponownego układania bloków przy wnoszeniu poprawek.

P.S. Trochę oszukałem: nie lubię tymczasowych rozwiązań, ponieważ nie ma nic bardziej stałego, niż czasowe. Mam nadzieję, że dany instrument i podejście pomoże Wam zaoszczędzić czas.

Ivan Alyakskin 
Software Consultant

Udostępnij

Masz jeszcze jakieś pytania?
Skontaktuj się z nami
Thank you!
The form has been submitted successfully.