Proste formaty tekstowe

Wprawdzie dobry kod znaczy więcej niż tysiąc słów, ale czasami kawałek dokumentacji jest po prostu nieodzowny. Osobiście uważam, że w tym względzie liczy się prostota i zaprzęganie do pracy takich formatów jak .doc czy nawet .pdf jest niemal zawsze grubą przesadą. Jest o wiele łatwiej, jeśli dokument daje się edytować zwyczajnym edytorem tekstowym.

Ale nawet wśród czysto tekstowych formatów występuje całkiem spora różnorodność. Mamy chociażby kilka opartych na XML-u – takich jak DocBook – że nie wspominając o nieśmiertelnym -u. Te i im podobne są językami znacznikowymi (markup languages) i poza sporymi możliwościami mają jedną wadę: są rozwlekłe. Stosunek “sygnału do szumu” nie jest w nich specjalnie wysoki, przez co w swojej surowej formie są one trudniejsze w czytaniu – a więc i w edycji.

Tej w wady są w dużym stopniu pozbawione formaty w stylu wiki, przypominające trochę różne spontaniczne pomysły na formatowanie czystego tekstu spacjami, myślnikami i gwiazdkami. Czasami nie mają one często zaawansowanych możliwości pozwalających na przykład na wstawianie tabel, ale w zakresie oferowanej funkcjonalności są zaskakująco często wystarczające. Z pewnością wystarczają chociażby do postów na forach czy ticketów w systemach do śledzenia błędów.

Jest tylko pewien szkopuł: jest ich mnóstwo. Poza kilkoma wariantami składni wiki, mamy też takie wynalazki jak Markdown albo reStructuredText. W sumie jednak stanowią one tylko część tych co bardziej znanych. Sytuacja przypomina tu trochę pewien szczególny komiks z xkcd. Skutkiem tego jest często konieczność sprawdzania, jakiej to składni używa akurat ta konkretna strona, na której piszemy post lub komentarz, jeśli tylko nie robimy tego regularnie.

Na szczęście przyswojenie sobie nowej składni tego rodzaju nie jest przeraźliwie wyczerpującym wysiłkiem umysłowym ;-) Niekiedy sprawę upraszcza też fakt wspierania przez dany serwis więcej niż jednego standardu – tak robi na przykład GitHub. I dlatego nawet istnienie kilkunastu podobnych formatów nie wydaje się być jakimś szczególnie wielkim problemem.
Porównajmy to chociażby z hipotetyczną sytuacją, gdy w użyciu jest kilka formatów podobnie rozbudowanych i skomplikowanych co XML… Brr :)

Jak się uczyć nowego API

Poznawanie nowych narzędzi programistycznych, bibliotek czy nawet platform to częsta konieczność w pracy kodera. Najczęściej jest to środek do osiągnięcia jakiegoś konkretnego celu projektowego, ale nierzadko możemy też zechcieć zagłębić się w nowe API dla samej przyjemności jego poznania. Jak się do tego zabrać? Są różne sposoby.

Możemy na przykład próbować jak najwięcej się o danej bibliotece dowiedzieć. W dzisiejszych czasach nie jest to trudne, bo standardem jest posiadanie dobrej (albo chociaż jakiejkolwiek ;]) dokumentacji. Ponadto wokół niemal każdej choć śladowo popularnej technologii natychmiast wyrastają internetowe społeczności, których dyskusje na forach (rzadziej już na grupach dyskusyjnych) mogą być również cennym źródłem informacji – zwłaszcza w przypadku wystąpienia problemów.
Postępując w ten sposób możemy zyskać bardzo szeroki i głęboki (jak morze :)) wgląd w funkcjonowanie danej biblioteki i jej strukturę, co może nam pomóc w jej użytkowaniu. Istnieje jednak szansa, że poprzez nadmierne skoncentrowanie się na opisach teoretycznych umkną nam ważne kwestie praktyczne.

Niejako przeciwną metodą jest jak najszybsze zajęcie się ową praktyką. W tym celu wystarcza zwykle przejrzenie różnorakich tutoriali (jeśli takowe są dostępne), a zwłaszcza dokładne przestudiowanie przykładowych fragmentów kodu. Zresztą eksperymentalne poznawanie nowej technologii może być wręcz kopiowaniem sampli, ich uruchamianiem, a następnie modyfikacją w celu zmiany sposobu działania, uelastycznienia lub poszerzenia o nową funkcjonalność.
Gdy w taki sposób zabieramy się do rzeczy, możemy szybko zobaczyć rezultaty. Jeśli jednak będziemy mieli pecha i pojawią się niespodziewane problemy, zaledwie pobieżna znajomość technologii może nam wydatnie utrudnić ich rozwiązanie. Poza tym takie kodowanie “na gorąco” wymaga nieporównywalnie częstszych wypadów na łono dokumentacji :)