Dlaczego tak wiele bibliotek nie ma / kiepskiej dokumentacji? [Zamknięte]

W podobny sposób jak w Jak projekty open source mogą odnieść sukces bez dokumentacji dotyczącej ich projektu lub architektury? pytanie, jestem ciekawy: dlaczego tak wielu bibliotekom brakuje dokumentacji użytkownika?

Mój pogląd jest taki:

1. Większość zgadza się, że czytanie kodu źródłowego jest trudniejsze niż pisanie kodu źródłowego.
2. Bez dokumentacji należy odczytać kod źródłowy biblioteki, aby korzystać z tej biblioteki.
3. Dlatego korzystanie z nieudokumentowanej biblioteki to więcej pracy niż zwykłe odtwarzanie biblioteki od zera.
4. W rezultacie, jeśli chcesz, aby ludzie korzystali z Twojej biblioteki, cholernie lepiej upewnij się, że jest udokumentowana.

Wiem, że wielu programistów nie lubi pisać dokumentów i zgodzę się, że może to być żmudna praca. Ale to niezbędna praca. Powiedziałbym nawet, że ważniejsze jest, aby biblioteka miała dobrą dokumentację niż najlepszy interfejs programisty na świecie. (Ludzie cały czas używają gównianych bibliotek; niewielu korzysta z nieudokumentowanych bibliotek)

Och, zauważcie, że kiedy mówię o dokumentacji, mam na myśli prawdziwą dokumentację. Nie płyta grzewcza Sandcastle / Javadoc / Doxygen.

Myślę, że w większości odpowiedziałeś na swoje pytanie: ponieważ w większości przypadków programiści po prostu nie będą się tym przejmować. Problem ten jest szczególnie rozpowszechniony w projektach wolontariackich.

Myślę jednak, że jest jeszcze jeden poważny problem: w wielu przypadkach programiści nie opracowali tak naprawdę ogólnego modelu działania ich biblioteki (lub po prostu mają trudności z wyraźnym sformułowaniem tego modelu). Niestety, wyartykułowanie tego modelu i dopasowanie części oprogramowania jest często najważniejszą częścią dokumentacji.

W typowym przypadku to, co zostało napisane, ma bardzo ogólny przegląd („To jest biblioteka do robienia fajnych rzeczy!”), A następnie bardzo niski opis (typ i opis każdego parametru, który ma zostać przekazany do każdej funkcji). Niestety, rzadko istnieje poziom pośredni na temat ogólnej teorii, w jaki sposób rzeczy powinny działać, w jaki sposób elementy pasują do siebie, itp. Wiele z tego sięga do faktu, że programiści często nie próbowali tworzyć, racjonalizować ani rozumieć swoich kod na tym poziomie szczegółowości. Przynajmniej w niektórych przypadkach, które widziałem, programiści, którzy zostali poproszeni o napisanie dokumentacji na tym poziomie, stwierdzili, że jest to dość problematyczne - do tego stopnia, że ​​wielu chciało przepisać kod, aby był bardziej zorganizowany i łatwiejszy do wyjaśnienia na tym poziomie Szczegół.

Dobre pisanie na tym poziomie abstrakcji jest często trudne - a jeśli programista tak naprawdę nie pomyślał o tym na tym poziomie abstrakcji, często uważają kod za nieco zawstydzający i mogą chcieć przepisać go, zanim będą szczęśliwi o wydaniu go w ogóle.

Myślę, że czasami dzieje się tak dlatego, że programista jest tak zawinięty w kod, że jest dla niego „oczywisty”, jak to działa i nie mogą zrozumieć, dlaczego nie byłoby to oczywiste dla nikogo innego. Podobnie, wiele stron internetowych z produktami mówi, jak wspaniały jest ich produkt, ale tak naprawdę nie mówi, co robi!

Sam zaznaczyłeś odpowiedź:

Wiem, że wielu programistów nie lubi pisać dokumentów i zgodzę się, że może to być żmudna praca.

Jako programiści lubimy pisać kod, ale niewielu z nas lubi także pisanie dokumentacji.

Chociaż każdy dobry programista zna wartość dobrej dokumentacji, zajmuje to również sporo czasu, aby zrobić to poprawnie. Ponieważ nie jest to przyjemne i zajmuje dużo czasu, umieszcza się go w stosie „do zrobienia później”, aby nigdy nie został osiągnięty na zadowalającym poziomie.

Na marginesie, programiście bardzo trudno jest napisać dokumentację na temat własnego produktu. Ponieważ tak dobrze znają system, pewne rzeczy są dla nich oczywiste. Części te często nie są wymieniane, mimo że nie są oczywiste dla konsumenta.

Pisanie dokumentacji to umiejętność. Jak wszystkie umiejętności wymaga praktyki. Czas i wysiłek, jaki poświęcamy na pisanie kodu, przynosi natychmiastowe korzyści. Widzimy nową funkcję, naprawiony błąd, lepszą prędkość. Pisanie dokumentacji ma opóźnioną wypłatę. Pomaga na dłuższą metę, ponieważ nowe osoby muszą pracować nad kodem lub jeśli wrócimy do pracy nad kodem miesiące lub lata później. To naturalne, że skupiamy się na krótkim okresie.

Moim zdaniem umiejętność pisania dobrej dokumentacji to jedna z kluczowych cech, która odróżnia świetnych programistów od przeciętnych programistów.

Osobą najlepiej wykwalifikowaną do pisania dokumentacji jest również osoba, która ma do tego najmniejszą motywację:

on (lub ona) jest:

• przede wszystkim opiekun biblioteki, a nie użytkownik. Im mniejsza i prostsza biblioteka, tym łatwiejsza jest jego praca. Utrzymanie połowy powieści oprócz kodu tylko utrudnia jego pracę,
• zna bibliotekę na wylot, więc nie potrzebuje dokumentacji,
• jest programistą, chce pisać kod, a nie dokumentację.

Nie mogę wymyślić nikogo, kto rzadziej „Hmm, naprawdę powinienem poświęcić kilka godzin na napisanie odpowiedniej dokumentacji na ten temat”. Dlaczego miałby

I oczywiście nie pomaga to, że istnieje legenda miejska, że ​​automatycznie generowane komentarze w stylu doksygen są wszystkim, czego potrzebujesz w zakresie dokumentacji.

Tak więc nawet w rzadkich przypadkach, gdy deweloper faktycznie jest gotowy napisać dokumentację, istnieje szansa 50/50, że programiści zostali poddani praniu mózgu, aby myśleć, że wszystko, czego potrzeba, to wypełnienie kilku takich komentarzy, przekazując ci klejnoty, takie jak że „funkcja Foo getFoo()zwraca obiekt typu Foo i jest on używany do uzyskania obiektu Foo”.

Dokumentacja? Nie potrzebujemy żadnej śmierdzącej dokumentacji!

Wiem, jak działa kod, więc dlaczego miałbym spędzać czas na dokumentowaniu mojego kodu? Poza tym muszę wykonać ten projekt do piątku i ledwo go zrealizuję ...