Jak przeszukiwać GitHub pod kątem udokumentowanej architektury

Szukam repozytoriów które mają dobrze, obficie, solidnie opisaną swoją architekturę.

Niestety jeszcze nie znalazłem możliwości jak to sprawnie robić.

Teraz po prostu wertuję GitHub pod kątem kompletnych systemów/aplikacji, szukam tych co mają dużo gwiazdek i/lub żywą społeczność i patrzę co ma w środku.

Ale to jest szukanie igły w stogu siana.

Brzmi to trochę jakby brakowało na rynku toola który ocenia i interpretuje GitHub, indeksuje i taguje pod dowolnym kątem.

Być może muszę się lepiej przyjrzeć tzw. "awesome lists", a może szukać po tym czy dane repo zawiera pliki w jakimś (lubianym przez opisywaczy architektury) formacie. To ostatnie dałoby się zautomatyzować dobrze, tylko że architekturę z powodzeniem da się opisać po prostu w GitHubowym readme a to ma każde repo.

Jeśli dobrze rozumiem, to nie chodzi ci o jakość samej architektury, tylko o jakość dokumentacji?

Jaki jest twój usecase? Chcesz się nauczyć robić lepszą architekturę i chcesz wiedzieć, gdzie są repozytoria, z których można się tego nauczyć?

Ja nie zrozumiałem o co OP pyta, może nie jestem targetem tego wątku ;)

Tak, chodzi o naukę dokumentowania architektury, niż samej architektury czy jej implementacji.

Przy czym zależy mi na przykładach raczej rzeczywistych a nie szkoleniowych czy wyobrażonych.

Ale tego lepiej się uczyć z książek a nie z repo randomow. Jest klika rodzajów dokumentowania architektury. Pytanie który cie interesuje.

Biblioteka piston_window ma graf zależności: https://github.com/PistonDevelopers/piston_window

Github pozwala wyszukiwać pliki w wybranym formacie, np plantuml: https://github.com/search?q=language%3APlantUML&type=code&ref=advsearch

Inne podejście: istnieje seria tomików popularno-dokumentacyjnych https://aosabook.org/, streszczająca zastosowane rozwiązania architektoniczne w znanym oprogramowaniu - można przewertować i zobaczyć, czy mają coś konkretniejszego.

Myślę, że może zamiast przeglądać bezpośrednio repa na GH, można by bardziej sięgnąć po dokumentacje na stronach danego narzędzia.

Np. w dokumentacji Postgresa opisują również internale, co tam pod spodem się dzieje w tych bazach danych. Rzeczy, których nie widać z perspektywy użytkownika.

Albo w dokumentacji Kubernetes też opisują różne koncepcje, jak tam te klastry w środku wyglądają itp.
https://kubernetes.io/docs/concepts/architecture/

Albo tutaj ktoś opisuje internale Reacta:
https://jser.dev/series/react-source-code-walkthrough/
pokazuje diagramy, jak ten React pod spodem działa, wrzuca kawałki kodu źródłowego Reacta. Dość wizualne to jest.

Fajne rzeczy, idę czytać, dzięki.

a może szukać po tym czy dane repo zawiera pliki w jakimś (lubianym przez opisywaczy architektury) formacie.

Spotkałem się z opisywaniem architektury w formie ADR: https://github.com/joelparkerhenderson/architecture-decision-record. Można szukać takich dokumentów wg stringu adr w ścieżce do pliku, często są to np. adr/01-temat.md itp.

Ja bym odwrócił tytułowe pytanie - jaka struktura repo ułatwia szukanie dokumentacji.

Przykłady struktury repozytorium, która ułatwia szukanie dokumentacji / opisu architektury:

• Podsumowanie dokumentacji w README.md + linki do innych dokumentacji i katalogów w tym samym repo
• Plik README.md dla każdego modułu aplikacji, np. gdy monorepo zawiera kilka powiązanych pakietów lub bibliotek
• Katalog bezpośrednio w top-level repo, o nazwie wskazującej na to, że właśnie tam będzie dokumentacja np. /docs, /documentation
• Lubię dokumentować całość w Markdown

Wyszukiwarka GH i tak jest o niebo lepsza niż parę lat temu, ale wciąż średnia. Daleko jej do tego, co mogłem robić lata temu mając dostęp do sourcegraph. Jeśli repo trzeba się konwencji jak określony format pliku lub używanie prefixów - da się jeszcze coś znaleźć.