Programiści Dlaczego nie należy pomijać dokumentacji

W dziedzinie rozwoju aplikacji mobilnych, aplikacji internetowych, aplikacji na komputery stacjonarne lub bibliotek JavaScript dokumentacja odgrywa ważną rolę, która może decydować o sukcesie rozwoju oprogramowania. Ale jeśli kiedykolwiek zrobiłeś dokumentację, zgodziłbyś się ze mną, że jest to najmniej ulubiona rzecz dla programistów.

W przeciwieństwie do pisania kodu (co zapisali programiści), dokumentacja (której nie zrobiliśmy) musi i powinna być łatwo strawiona przez każdy. Technicznie musimy przetłumaczyć język maszynowy (kod) na język zrozumiały dla ludzi, co jest trudniejsze niż się wydaje.

Chociaż może to być bardzo uciążliwe, pisanie dokumentacji jest ważne i przyniesie korzyści użytkownikom, współpracownikom, a zwłaszcza samemu.

Dobra dokumentacja pomaga użytkownikom

Dokumentacja pomaga czytelnikowi zrozumieć, jak działa kod, oczywiście. Ale wielu programistów popełnia błąd zakładając, że użytkownicy oprogramowania będą biegli. Dlatego dokumentacja może być cienkim materiałem, pomijając wiele zasadniczych elementów, które powinna zawierać od początku. Jeśli jesteś biegły w języku, możesz wymyślić coś z własnej inicjatywy; jeśli nie jesteś, to jesteś zgubiony.

Dokumentacja przeznaczona dla użytkowników zazwyczaj składa się z praktycznego zastosowania lub “jak”. Podstawową zasadą przy tworzeniu dokumentacji dla użytkowników ogólnych jest to powinno być jasne. Używanie słów przyjaznych człowiekowi jest lepsze niż terminów technicznych lub żargonu. Prawdziwe przykłady użycia również będą bardzo mile widziane.

Dobry projekt układu naprawdę pomaga użytkownikom skanować każdą sekcję dokumentacji bez wysiłku. Kilka dobrych przykładów (zwanych moimi ulubionymi) to dokumentacja Bootstrap i WordPress ' “Pierwsze kroki z WordPress”.

Pomaga to innym programistom

Każdy programista będzie miał swój własny styl kodowania. Ale jeśli chodzi o pracę w zespole, często będziemy musieli dzielić kody z innymi członkami zespołu. Jest więc niezbędne mieć konsensus w sprawie standardu aby wszyscy byli na tej samej stronie. Odpowiednio napisana dokumentacja byłaby referencją potrzebną zespołowi

Ale w przeciwieństwie do dokumentacji użytkownika końcowego, ta dokumentacja zazwyczaj opisuje procedury techniczne jak konwencja nazewnictwa kodu, pokazująca, w jaki sposób należy skonstruować poszczególne strony oraz jak działa interfejs API wraz z przykładami kodu. Często też musielibyśmy napisać dokumentację wraz z kodem (znanym jako komentarze) opisać, co robi kod.

Ponadto w przypadku, gdy masz dołączanie nowych członków Twój zespół później, ta dokumentacja może być skutecznym sposobem na ich wyszkolenie, więc nie musisz podawać kodu 1 na 1.

Dziwnie to również pomaga koderowi

Zabawne w kodowaniu jest to, że czasami nawet sami deweloperzy nie rozumieją kodu, który napisali. Jest to szczególnie prawdziwe w przypadkach, gdy kody pozostawiono nietknięte przez miesiące lub nawet lata.

Nagła potrzeba ponownego odwiedzenia kodów z tego lub innego powodu spowodowałaby, że ktoś zastanawiałby się, co działo się w ich umysłach, kiedy pisali te kody. Nie zdziw się: byłem już w tej sytuacji. To jest dokładnie kiedy ja życzył Udokumentowałem mój kod poprawnie.

Dokumentując swoje kody, będziesz mógł szybko i bez frustracji dotrzeć do sedna swoich kodów, oszczędzając Ci dużo czasu, który możesz przeznaczyć na wprowadzenie zmian w.

Co czyni dobrą dokumentację?

Istnieje kilka czynników, które tworzą dobrą dokumentację.

1. Nigdy nie zakładaj

Nie zakładaj, że Twoi użytkownicy wiedzą co ty wiem jak i co one chcę wiedzieć. Zawsze jest lepiej zacząć od samego początku niezależnie od poziomu zaawansowania użytkowników.

Jeśli na przykład zbudowałeś wtyczkę jQuery, możesz czerpać inspirację z dokumentacji SlickJS. Pokazuje, jak uporządkować HTML, gdzie umieścić CSS i JavaScript, jak zainicjować wtyczkę jQuery na jej najbardziej podstawowym poziomie, a nawet pokazuje kompletny końcowy znacznik po dodaniu wszystkich tych rzeczy, co jest czymś oczywistym.

Najważniejsze jest to, że dokumentacja jest napisana z myślą użytkownika, a nie programisty. Podejście do własnej dokumentacji w ten sposób da ci lepszą perspektywę w organizowaniu własnego dzieła.

2. Postępuj zgodnie ze standardem

Dodając dokumentację zgodną z kodem, użyj standardu oczekiwanego od języka. Zawsze dobrze jest opisać każdą funkcję, zmienne, a także wartość zwracaną przez funkcję. Oto przykład dobrej dokumentacji inline dla PHP.

 / ** * Dodaje niestandardowe klasy do tablicy klas treści. * * @param array $ classes Klasy dla elementu body. * @return array * / function body_classes ($ classes) // Dodaje klasę bloga grupowego do blogów z więcej niż 1 opublikowanym autorem. if (is_multi_author ()) $ classes [] = 'blog grupowy';  return $ classes;  add_filter ('body_class', 'body_classes');

Poniżej znajduje się kilka odniesień do formatowania dokumentacji inline za pomocą najlepszych praktyk w PHP, JavaScript i CSS:

PHP: Standard dokumentacji PHP dla WordPress
JavaScript: UseJSDoc
CSS: CSSDoc

Jeśli używasz SublimeText, zasugerowałbym zainstalowanie DocBlockr, który sprytnie wypełni Twój kod dokumentacją inline.

3. Elementy graficzne

Używaj elementów graficznych, mówią lepiej niż tekst. Nośniki te są przydatne, zwłaszcza jeśli budujesz oprogramowanie z interfejsem graficznym. Możesz dodawać elementy wskazujące, takie jak strzałki, koło lub wszystko, co może pomóc użytkownikom dowiedzieć się, gdzie iść, aby wykonać kroki, bez zgadywania.

Oto przykład z aplikacji Tower, z której możesz czerpać inspirację. Skutecznie wyjaśniają, w jaki sposób kontrola wersji działa w przyjemny sposób, co czyni go bardziej zrozumiałym niż przy użyciu zwykłych linii poleceń.

4. Dzielenie

Możesz rozważyć zawarcie kilku elementów w dokumentacji w listach punktowanych i tabelach, ponieważ dzięki temu dłuższa zawartość będzie łatwiejsza do skanowania i czytania dla użytkowników.

Dodaj tabelę treści i podziel dokumentację na łatwo przyswajalne sekcje, zachowując przy tym znaczenie każdej sekcji z tym, co będzie dalej. Trzymaj to krótko i prosto. Poniżej znajduje się przykład ładnie zorganizowanej dokumentacji na Facebooku. Spis treści zabiera nas tam, gdzie chcemy przejść jednym kliknięciem.

5. Popraw i zaktualizuj

Na koniec przejrzyj dokumentację pod kątem błędów i skoryguj w razie potrzeby lub za każdym razem, gdy pojawią się istotne zmiany w produkcie, oprogramowaniu lub bibliotece. Twoja dokumentacja byłaby dla nikogo bezużyteczna, gdyby nie była regularnie aktualizowana obok Twojego produktu.