O czym nie mówią tutoriale?

Niedzielne przemyslenia. Dowiedzielismy sie o nowej technologi, lykamy ja do projektu niczym Reksio szynke i po pewnym czasie dostajemy niestrawnosci, bo w tutorialu/prezentacji zabraklo informacji o czyms waznym. Pytanie, czego jeszcze brakuje w mojej liscie?

• utrzymanie uslugi (np. duzy cluster Cassandry)
• bezpieczna konfiguracja
• aktualizacja CVE bezposrednio dla uslugi
• aktualizacja dependencji (np. Netty)
• RBAC
• niekomatybilnosc z wersjami innych technologii
• backup/restore
• koszty w cloudzie
• disaster recovery
• upgrade
• zwykly reboot uslugi i wplyw na reszte systemu
• Nasz przypadek uzycia jest nieco inny niz pokazany i akurat ciezko zrobic customizacje pod nasz konretny scenariusz
• wydajnosc

Na razie tyle.

EDIT:

Tutaj dopisuje co mi przyszo jeszcze do glowy albo wywnioskowalem z odpowiedzi:

• moj przypadek uzycia jest inny niz Twoj
• skalowanie aplikacji
• complexity
• uzywanie nowej technologii jak czegos innego, mamy mlotek -> wszedzi ewidzimy gwozdzie.
• byc moze mamy lepsza alternatywe. Np. pod katem wydajnosci Postgres + JSON prawdopodobnie w wielu wypadkach jest lepszym wyborem.
• licencje, czesc opcji moze byc platna
• debugging
• Learning curve
• data durability/data losss (Memcached)
• integracja
• single point of failure (Zookeeper)
• availability
• montioring/alerting
• stabilnosc
• maintenance (pielegnacja)

Tutoriale w większości pokazują najprostszy przypadek użycia, który nie ma nic wspólnego ze światem rzeczywistym. Ile to już widziałem rozwiązań pokazujących jak implementować mikroserwisy na podstawie wydumanych problemów nie mających nic wspólnego z rzeczywistością biznesową, tylko dlatego, że autorowi tak było łatwiej, albo nie miał doświadczenia w implementacji takich rozwiązań w rzeczywistym środowisku.

Nasz przypadek uzycia jest nieco inny niz pokazany i akurat ciezko zrobic customizacje pod nasz konretny scenariusz

Często, choćby np. trochę inna konfiguracja albo ktoś odpala coś na innej platformie czy na innej wersji platformy. Albo wymagany jest jakiś soft zainstalowany w kompie. Wtedy stackoverflow pomaga.

No i ogólnie tutoriale często zakładają, że ludzie będą je przechodzić od A do Z (tak samo sekcje getting started w dokumentacjach).

I myślę, że takie podejście ma sens z perspektywy twórcy tutoriala / dokumentacji - napisać ładnie wszystko od A do Z i niech ludzie to przechodzą po kolei kolejne kroki. To wiele ułatwia, jak każdy będzie robił tak samo, to jak komuś coś nie wyjdzie, to będzie łatwiej mu pomóc. Dla tradycyjnego odbiorcy tutoriala pewnie też jest łatwiej mieć wszystko rozpisane od A do Z.

Problem jednak się robi w tym, jak idziemy w turbonaukę. Tradycyjne tutoriale video zajmują masę czasu (nawet w 2x tempie), w dokumentacjach też jest masę tekstu do czytania, więc ja często na wyrywki to czytam. I wtedy czasem nie doczytam o czymś ważnym, co było omawiane wcześniej i mi nie działa.

Czyli tak:

• z jednej strony fajnie, jakby tutorial/dokumentacja była przyjazna początkującym, którzy mają dużo czasu na czytanie i oglądanie video
• ale też fajnie, jakby tutorial/dokumentacja pozwalał na jakiś skrót dla osób, które chcą po prostu szybko coś odpalić, a nie przebijać się przez ścianę tekstu wprowadzającego czy słuchać wody jak na wykładzie na studiach

Być może to powinny być inne tutoriale? Normalne tutoriale, gdzie ktoś by wyjaśniał szczegółowo oraz "antytutoriale", gdzie byłoby mało tłumaczenia, a bardziej zwięzły opis i pokazywanie konkretnych przykładów? (chociaż czy nie jest tak, że ChatGPT to już potrafi?)

@LukeJL: Ja nie chce krytykowac tutoriali, bardziej na zasadzie -> widzimy gore lodowa, ale nie wiemy co kryje sie pod spodem.
Ew. jak na tym obrazku, uswiadomic sobie co moze sie kryc pod woda: https://www.reddit.com/r/MemeTemplatesOfficial/comments/ly6rhq/dinosaur_jumping_to_a_deep_water/

No sam się zabieram za robienie tutoriali, więc podłapałem temat i rozkminiam.
Mam dylemat właśnie, czy iść w bardziej łopatologiczne tłumaczenia, czy może bardziej w konkretne przykłady i krótki opis. Czy może coś pośredniego.

Żaden tutorial nigdy też nie pisze o tym jak testować te elementy. Pamiętam, że jak pisałem edytor do 4programmers.net i chciałem dodać autocomplete, to w całej dokumentacji nie było ani słowa o tym jak przetestować ten autocomplete. Zeszło mi jakieś 40h żeby to samemu wykminić.

To samo tyczy się wszelkich innych integracji lub providerów: sms, maile, kolejki, e-money, oAuth - wszystkie te dokumentacje są pełne przypadków użycia - ale kiedy się użyje tej biblioteki w swoim projekcie, i chce się napisać dobry test pod te integracje, to dokumentacja o tym milczy. Dla przykładu: https://github.com/smsglobal/smsglobal-php mamy w Sms Global Api rozdział "Verify OTP", który pisze że weryfikacja OTP jest "bardzo prosta", bo wystarczy jedna metoda. Ale jak wysłać fake'owe OTP w testach, żeby zweryfikować usera? No właśnie, o całkowita cisza - musisz sam na to wpaść, i jak już napiszesz dobry test który faktycznie umie wysłać fake'owe OTP, to bardzo prawodpodobne że kod który powstanie będzie bardzo różny od przykładu z dokumentacji.

Jedynym nieznaczącym nic wyjątkiem są frameworki (laravel, django, spring, RoR), które podają mniej niż minimum przykładów z testami, ale to nie jest i tak na temat bo te testy nie tyczą się samego frameworka, tylko naszej aplikacji w tym frameworków, czyli problem nadal ten sam.

Nawet tutoriale z głupią aplikacją konsolową brzmią:

• Tutorial: Żeby użyć argumentów, użyj sys.argv - to jest bardzo, bardzo proste!
• User: No dobra, ale jak napisać test pod to?
• Tutorial:
  

Co jest w ogóle dodatkowo śmieszne, bo dochodzimy do momentu odwróconego wnioskowania. Początkujący programiści często wytykają jak np użycie input() oraz println() jest "łatwe", bo mało pisania; a dodanie konstruktora i wstrzyknięcie klasy jest "trudne" bo jest dużo pisania; podczas gdy żeby przetestować input()/println() to trzeba się nieźle narobić wstawiając fake'owe stdin/stdout i martwiąc się o spacje, entry i kodowanie; a żeby przetestować taką klasę to
wystarczy anonimowa implementacja.

Kolejną częstą ofiarą są np biblioteki które w jakiś sposób integrują w system na którym działamy, np operują na plikach lub zmiennych środowiskowych. Dobrym przykładem jest gdzie ArgumentParser z pythona umie się dopasować szerokością odpowiedzi do szerokości terminala. W dokumentacji jest to opisane jako "bardzo proste oraz automatyczne". Niby racja. Ale napisanie testu pod to wymaga spawnowania procesu z przekazaniem zmiennej środowiskowej, żeby w ogóle zrekreować to zachowanie w środowisku testowym, nie ma żadnej flagi do przekazania.

Innym przykładem są wszelkie rozwiązania które są "szybkie i proste", np hooki w reacie: useState(), useEffect(). Dokumentacja reacta opisuje testowanie komponentów snapshotami, ale te snapshoty w ogóle nie testują hooków: czyli mamy do wyboru albo zostawić je nieprzetestowane, albo praktycznie napisać je samemu od nowa, żeby móc napisać testy pod nie.

Jeśli dokumentacja już zrobi łaskę i napisze chociaż słowo o testowaniu, to często też łamie enkapsulacje. W Laravelu w dokumentacji ORM' jest malutki rozdział o tym jak podmienić ORM i modele tak żeby nie strzelały do bazy (co jest określone jako "can be helpful when testing", ho, ho), ale to przecież całkowicie łamie enkapsulacje naszego kodu i przywiązuje testy do implementacji. Nie ma całkowicie opisanego jak to poprawnie przetestować - czyli w sposób niezależny od ORM'a, np bazą in-memory.

Jeśli weźmie się testowanie każdej biblioteki na poważnie, to każda dokumentacja pod tym względem jest worse then useless - bo jeśli będziesz followować taką dokumentację i tutorial, to bardzo prawdopodobne że wytworzysz nietestowalny kod.

@LukeJL: najbardziej lubie use case zblizony do takiego z zycia rozpisany krok po kroku. Inna sprawa, ze gdyby to wszystko co wymieniam uwzgledniac w tutorialu, kazdy tutorial bylby ksiazka.

lubie use case zblizony do takiego z zycia

A czym jest życiowy use case ?
Bo wydaje mi się, że wiele narzędzi/bibliotek/frameworków ma bardzo szerokie zastosowanie i można wykorzystać to samo narzędzie zarówno do jakiegoś prostego CRUD'a, jak i w systemie dla banku. Zarówno realnym scenariuszem jest stworzenie TODO list, jak i klonu allegro. Także co by miało decydować, na ile jakiś przykład/scenariusz jest książkowy, a na ile realny?

Te niby życiiowe to właśnie jest przykład podejścia "nie znam narzędzia dobrze, ale klepałem jeden program w pracy to przedstawie go jako ogólny przykład".

WhiteLightning napisał(a):

@LukeJL: najbardziej lubie use case zblizony do takiego z zycia rozpisany krok po kroku. Inna sprawa, ze gdyby to wszystko co wymieniam uwzgledniac w tutorialu, kazdy tutorial bylby ksiazka.

Każdy zły tutorial.

Dobre tutoriale są zwięzłe, ale też obszerne w informacje, nie koniecznie obszerne w objętność.

Riddle napisał(a):

Żaden tutorial nigdy też nie pisze o tym jak testować te elementy. Pamiętam, że jak pisałem edytor do 4programmers.net i chciałem dodać autocomplete, to w całej dokumentacji nie było ani słowa o tym jak przetestować ten autocomplete. Zeszło mi jakieś 40h żeby to samemu wykminić.

Słuszna uwaga. Chociaż to też pytanie, czy robimy tutorial, który ma ludziom pomóc napisać PoC i tylko tyle, czy może mamy pomóc im napisać coś, co będzie się nadawać na produkcję. Czyli z testami i ładnym kodem.

I to jest dylemat - bo w tutorialach jest

• albo zrobione wszystko byle jak, "na pałę" (efekt taki, że potem ludzie piszą spaghetti na produkcji, bo tak się nauczyli w tutorialach)
• albo przeinżynierowanie, gdzie tłumaczą przez 80% czasu rzeczy niezwiązane z głównym tematem, a np. robią jakieś pomocnicze klasy i w sumie przerabiasz tutorial i dalej nie wiesz, jak coś zrobić (a potem ludzie myślą, że te abstrakcje są potrzebne, bo tak było w tutorialu. Cargo cult przeinżynierowania)

Myślę, że może to też mogłyby być różne rodzaje tutorialów:

• jak napisać PoC danej rzeczy, prosto do celu, bez zbędnych abstrakcji
• jak napisać daną rzecz tak, jakby się pisało na produkcji, z odpowiednimi abstrakcjami i testami

Może takie tutoriale mogłyby być oznaczone jakoś specjalnie badge'ami:

• PoC vs. production grade
• tests
• beginner
• advanced

itp. żeby od razu było widać, jakiego rodzaju to tutorial? Chociaż nie wiem, czy zawsze twórca tutorialu by to umiał skategoryzować.

no ale bez tego, to szukasz czegoś i później się okazuje, że w 12 częściowym tutorialu ktoś przez pierwsze 2 części tłumaczy jak zainstalować Node.js i jak działa Git, mimo że tutorial jest o czymś innym zupełnie XD

Riddle napisał(a):

Co jest w ogóle dodatkowo śmieszne, bo dochodzimy do momentu odwróconego wnioskowania. Początkujący programiści często wytykają jak np użycie input() oraz println() jest "łatwe", bo mało pisania

Ale pisanie w czysty sposób nie byłoby trudne nawet dla początkującego. Wersja z println(czy raczej z console.log) z efektami ubocznymi wrzuconymi bezpośrednio do funkcji:

function printAnimal(animal) {
   console.log(`This is animal ${animal.kind()} and it says ${animal.say()}`);
}
printAnimal(new Cat);
printAnimal(new Dog);

wersja czysta, gdzie funkcja tworzy stringa i go zwraca:

function printAnimal(animal) {
   return `This is animal ${animal.kind()} and it says ${animal.say()}`;
}
console.log(printAnimal(new Cat));
console.log(printAnimal(new Dog));

druga wersja wcale nie jest bardziej skomplikowana od pierwszej, a jednak początkujący zwykle będą pisać w pierwszy sposób. Nikt im nie powiedział, że owszem, za pomocą console.log można sobie coś wyświetlić do debugowania, ale jak się pisze na serio, to jednak bardziej eleganckie jest jak funkcje zwracają wartość, którą my dopiero wyświetlimy.

Większość z tego co wymieniłeś to są nieuświadomione błędy.
Łatwo je przeoczyć projektując coś, bo zwykle skupiamy się na pewnym rozwiązaniu, a umkną nam problemy, które mogą gdzieś przy wykorzystywaniu tego wyjść.

Wydaje mi się niemożliwe skupić się na tych wszystkich aspektach, przydaje się tutaj jakiś rój użytkowników, społeczeństwa, które korzysta i zgłasza jakie trudności zauważy z danym softwarem.

Pewne problemy jakie wymieniłeś, mogą nie mieć żadnego znaczenia, a pewne mogą być mega ważne, tutaj statystyka, większość użytkowników mogła by zadecydować, jak większość programistów tak i tak stwierdzi to można potem inne własności posterior probability wynioskować.

A tutoriale skupiają się jak dla mnie na wstępnej instrukcji odpalenia wersji podstawowej systemu.
Potem już tylko użytkownicy, programiści i inni ludzie, którzy są w kręgu tego oprogramowania zgłaszają problemy jakie oni napotykają w różnych dziedzinach, samemu trudno wszystko wywnioskować, można wnioskować na podstawie problemów jako developer, a się okaże, że są problemy z poziomu użytkownika, których programista nie zauważy, bo wszyscy inaczej postrzegamy świat.

Problemem tutoriali jest to że ich twórcy często dobierają sobie problem do rozwiązania a Ty jako programista musisz znaleźć rozwiązanie do problemu.

Kosztach ;)

WhiteLightning napisał(a):

@LukeJL: najbardziej lubie use case zblizony do takiego z zycia rozpisany krok po kroku. Inna sprawa, ze gdyby to wszystko co wymieniam uwzgledniac w tutorialu, kazdy tutorial bylby ksiazka.

Noi bardzo dobrze - niech takie będą. Z odpowiednim spisem treści, opcją "szukaj" i odpowiednimi linkami między stronami - nie powinno być problemu.

1. Proste i uczciwe przyznanie pod jakim kątem wybrana technologia jest ograniczona. Jakie są jej wady w zestawieniu z prostszymi alternatywami.

2. Jaki jest najbardziej skrajny przypadek w którym efektywnie projekt można prowadzić bez tej technologii?

3. Opisać w jaki sposób wybrana technologia wpływa na myślenie. Przedstawić główne zasady jakie warto znać i jakie torują podejście do pracy z wybranym narzędziem.

4. Przedstawić czy są możliwe opcje użycia w mniejszym zakresie projektu, albo na dowolnym etapie projektu, albo w połączeniu z innymi technologiami, które potencjalnie mogłaby zniwelować jakieś braki.

Wspólny problem tutoriali i często dokumentacji technicznej, to marketingowe podejście do opisywanego rozwiązania. Jeżeli ktoś wrzuca tutorial na YT, czy jakąś platformę MOOC, to przecież nie zacznie szkolenia od "ta technologia generuje więcej problemów niż korzyści, olej resztę treści bo nie warto się w to pakować".

Taki mocny przypadek z którym się zetknąłem ostatnio, to usługa kolejkowa, która co prawda ma georeplikację (w każdym razie ją deklaruje), ale obejmuje ona jedynie konfigurację, a nie wiadomości w kolejkach. Ta informacja była gdzieś głębiej w dokumentacji, ale też nie była podana wprost. Opisano co jest replikowane pomiędzy regionami, ale fakt nie przenoszenia wiadomości pominęto.

Niby można wywnioskować, ale to jak z typową promocją konta w banku, gdzie łapie się klientów na to co jest za darmo, pomijając całkowicie to co kosztuje 3x drożej niż u konkurencji. W efekcie iluś tam klientów da się złapać na "w pełni darmowe konto", a później się dowiaduje, że ok, konto jest darmowe, ale pod jakimiś tam warunkami, a za kartę trzeba zapłacić 20zł miesięcznie.

Takie bardziej ogólne spostrzeżenie, to "kupując" cokolwiek, nie ważne czy jest to toster, czy nowa technologia skupiamy się na potencjalnych zyskach, a nie kosztach i wprowadzimy do projektu jakąś bibliotekę, bo częściowo rozwiąże nasz aktualny problem, kompletnie nie zwracając uwagi na koszty, jeżeli nie są one natychmiastowe. Wybieramy te narzędzia jak typowy klient telefon komórkowy - jest fajny, to go bierze, bo "za darmo", bo w abonamencie.