GitHub jako repozytorium dokumentacji projektowej, wersjonowanie opisów i zestawień

Znasz to? Siedzisz nad opisem technicznym, poprawiasz trzeci raz parametry instalacji, zapisujesz plik i w katalogu roboczym ląduje kolejny egzemplarz: opis_techniczny_v3_poprawiony_2_FINAL.docx. Albo otwierasz zestawienie materiałowe i nagle okazuje się, że kolega edytował swoją wersję na dysku wspólnym i Twoje zmiany przepadły. Brzmi znajomo? Właśnie przez to w małych biurach projektowych chaos dokumentacyjny jest normą, a nie wyjątkiem.

Szukałem narzędzia, które pomoże mi ogarnąć ten bałagan. CDE (Common Data Environment) typu Autodesk Docs czy Trimble Connect są super, ale dla pojedynczego projektanta lub 3-osobowego zespołu ich koszt i poziom skomplikowania to przesada. Potrzebowałem czegoś prostego, taniego i sprawdzonego. Okazuje się, że narzędzie, które kojarzyłem głównie z programowaniem, może być odpowiedzią na problemy wersjonowania dokumentacji biurowej. Mowa o GitHubie.

W tym wpisie pokażę:

• dlaczego GitHub sprawdza się w przechowywaniu dokumentacji projektowej,
• co konkretnie możesz tam trzymać (a czego nie),
• jak wykorzystać gałęzie i pull requesty w codziennej pracy,
• gdzie leżą granice tego rozwiązania,
• jak zacząć w 10 minut za darmo.

GitHub to nie CDE i nie próbuje nim być

Zacznijmy od ważnego założenia. GitHub to platforma do hostowania repozytoriów git – systemu kontroli wersji. Powstał dla kodu źródłowego i w tym jest bezkonkurencyjny. Nie jest Common Data Environment dla branży budowlanej i nie udaje, że nim jest. Nie otworzysz w nim modelu Revita, nie zrobisz clash detection, nie przeprowadzisz BIM kolizji. Ale też nie tego od niego chcemy.

GitHub ma być narzędziem do porządkowania dokumentów tekstowych projektu: opisów technicznych, zestawień, notatek, protokołów. I w tej roli sprawdza się doskonale – pod jednym warunkiem: wiesz, co wkładasz i jakie są ograniczenia.

Dlaczego GitHub, a nie folder na serwerze?

To najprostsze pytanie i jednocześnie najważniejsze. Folder na dysku wspólnym czy w chmurze (OneDrive, Google Drive) nie ma historii zmian. Owszem, OneDrive ma wersjonowanie, ale próbowałeś kiedyś znaleźć konkretną zmianę sprzed dwóch miesięcy? To jak szukanie igły w stogu siana.

GitHub daje Ci trzy rzeczy, które zmieniają wszystko:

• Pełna historia zmian – widzisz kto, kiedy i co dokładnie zmienił w pliku. Możesz cofnąć się do dowolnej wersji,
• Możliwość pracy równoległej – kilka osób może edytować ten sam dokument w różnych gałęziach bez ryzyka nadpisania swojej pracy,
• Pull requesty jako proces akceptacji – zanim zmiany trafią do wersji ostatecznej, ktoś je sprawdzi i zatwierdzi.

Co konkretnie możesz trzymać w repozytorium?

GitHub świetnie radzi sobie z plikami tekstowymi i małymi dokumentami. Oto co sam wrzucam do repo projektu:

• Opisy techniczne (.docx, .md) – cała dokumentacja branżowa, opisy instalacji, parametry,
• Zestawienia materiałowe i kosztorysy (.xlsx) – arkusze z ilościami, cenami, zestawieniami,
• Notatki ze spotkań i protokoły (.md, .txt) – uzgodnienia z inwestorem, uwagi z narad koordynacyjnych,
• Specyfikacje i ekspertyzy (.pdf, .docx) – pod warunkiem, że plik nie przekracza 100 MB,
• Obliczenia (.xlsx, .pdf) – na przykład bilanse cieplne czy dobory urządzeń,
• Własna baza notatek projektanta – checklisty, schematy postępowania, szablony.

Uwaga: format .docx i .xlsx to pliki binarne. Git widzi je jako całość i nie pokaże Ci ładnego diffa (porównania zmian) w trybie tekstowym. Mimo to historia wersji i możliwość powrotu działa w pełni. Jeśli chcesz widzieć konkretne zmiany, lepiej używać plików Markdown (.md) lub zwykłych txt – dla nich diff działa perfekcyjnie.

Praktyczny workflow – gałęzie i wersje dokumentu

Największą zaletą gita są gałęzie (branches). W kontekście dokumentacji projektowej możesz je wykorzystać tak:

• main (lub master) – wersja ostateczna, zatwierdzona, archiwalna. Tylko gotowe dokumenty,
• do-uzgodnienia – gałąź robocza, gdzie wprowadzasz zmiany i czekasz na opinie,
• wersja-dla-inwestora – odgałęziona wersja, którą pokazujesz klientowi,
• archiwum – zamknięte wersje dokumentacji z poprzednich etapów projektu.

Brzmi jak overkill dla pojedynczego projektanta? Być może. Ale wystarczy raz cofnąć się o miesiąc, zobaczyć, że w opisie technicznym była błędna średnica rury, i dzięki historii zmian przywrócić poprawną wartość – a przekonasz się, że to działa.

Issues jako lista uwag do dokumentacji

Kolejna funkcja, którą uwielbiam, to Issues. To taki system ticketowy wbudowany w repozytorium. W praktyce projektowej wygląda to tak: dostajesz uwagi od inwestora do opisu technicznego. Tworzysz Issue z tytułem „Uwagi inwestora do opisu – instalacja wentylacji”, wypisujesz punkty do poprawy i przypisujesz je do siebie lub kolegi.

Każde Issue może być dyskusją, możesz dodawać zrzuty ekranu, załączniki, tagi (na przykład „pilne”, „do sprawdzenia”, „archiwum”). Gdy poprawki są gotowe, zamykasz Issue i masz pełną historię – co, kiedy i dlaczego zostało zmienione.

Pull request jako proces akceptacji dokumentu

Pull request (PR) to moja ulubiona funkcja w kontekście pracy zespołowej. Działa tak: tworzysz nową gałąź, edytujesz opis techniczny, a następnie zgłaszasz PR do gałęzi głównej. Ktoś z zespołu (lub Ty sam, po odczekaniu jednego dnia) przegląda zmiany, dodaje komentarze i ostatecznie zatwierdza merge.

W małym biurze to złote rozwiązanie. Zamiast wysyłać „poprawiony opis techniczny v4″ mailem i czekać na odpowiedź, tworzysz PR, a kolega dostaje powiadomienie, że czeka na niego przegląd. Zero utraconych załączników, zero chaosu wersji.

GitHub Actions – automatyzacja generowania PDF

Jeśli lubisz automatyzację (a jako czytelnik tego bloga pewnie tak), GitHub Actions pozwala Ci zrobić ciekawą rzecz: automatycznie generować PDF z plików Markdown. Skonfigurujesz to w 15 minut – wystarczy plik .github/workflows/pdf.yml w repozytorium. Przy każdym pushu na gałąź main, GitHub sam przerobi Twoje notatki na ładny PDF i wrzuci go do artefaktów.

To rozwiązanie idealne, jeśli prowadzisz notatki projektu w Markdownie i chcesz mieć automatycznie generowany, gotowy do wydruku dokument.

Uczciwe ograniczenia – GitHub ma swoje granice

Muszę być z Tobą szczery. GitHub nie jest idealny i ma konkretne ograniczenia, które musisz znać, zanim zaczniesz:

• 100 MB na plik – to twardy limit. Większych plików nie wrzucisz przez standardowe push. Dotyczy to na przykład dużych PDFów z skanami dokumentacji,
• 1 GB na repozytorium (konto darmowe) – jeśli masz dużo zestawień Excel lub skanów, możesz szybko wypełnić limit. Plany płatne zaczynają się od 4 USD/miesiąc i dają więcej przestrzeni,
• Brak podglądu 3D – nie otworzysz modelu Revit ani IFC, nie zobaczysz geometrii. GitHub to nie CDE i nie próbuj go do tego używać,
• Brak narzędzi BIM – clash detection, zarządzanie rewizjami modeli, współpraca na modelu – to nie tu,
• Brak diffa dla plików binarnych – dla .docx czy .xlsx nie zobaczysz, co dokładnie zmieniono, tylko że plik się zmienił.

I właśnie dlatego na początku posta napisałem: GitHub to nie CDE. Jeśli potrzebujesz platformy do zarządzania modelami BIM, wybierz Autodesk Docs, Trimble Connect albo dał. Ale jeśli chcesz uporządkować dokumentację tekstową – GitHub może być tym, czego szukasz.

Dla kogo to ma sens?

To rozwiązanie skierowałbym do trzech grup:

• Indywidualni projektanci – prywatne repozytorium jako backup z historią zmian. Pracujesz sam, ale chcesz mieć pewność, że każda wersja dokumentu jest bezpieczna,
• Małe biura (2–5 osób) – zamiast wysyłać pliki mailem, współpracujecie przez repozytorium. Gałęzie, Issues i pull requesty wprowadzają porządek,
• Zespoły BIM, które potrzebują dodatkowego narzędzia – używacie CDE do modeli, ale dokumentację tekstową trzymacie w GitHubie jako bardziej elastycznym rozwiązaniu.

Jak zacząć w 10 minut?

Proces jest prostszy niż myślisz. Oto plan działania krok po kroku:

• Załóż konto na github.com (konto darmowe wystarczy),
• Kliknij zielony przycisk „New repository”, nazwij je np. „projekt-hala-produkcyjna”,
• Zaznacz „Private” (prywatne – tylko Ty i zaproszone osoby widzą zawartość),
• Zainstaluj Git na swoim komputerze (git-scm.com),
• Otwórz terminal, przejdź do katalogu z dokumentacją projektu i wpisz:

git init
git add .
git commit -m "Pierwsza wersja dokumentacji"
git remote add origin https://github.com/twoja-nazwa/projekt-hala-produkcyjna.git
git push -u origin main

To wszystko – Twoja dokumentacja jest już w GitHubie. Od tego momentu przed każdą większą zmianą robisz commit, piszesz co zmieniłeś i pushujesz do repozytorium. Po miesiącu pracy sam się zdziwisz, jak bardzo to porządkuje Twój warsztat.

Podsumowanie

GitHub to narzędzie, które – używane z głową – może znacząco poprawić jakość i porządek dokumentacji projektowej w małym biurze. Nie zastąpi CDE, nie obsłuży modeli 3D ani nie zrobi za Ciebie koordynacji międzybranżowej. Ale tam, gdzie chodzi o tekst, zestawienia i notatki – jest bezkonkurencyjny w stosunku ceny do możliwości.

Jeśli masz dość plików o nazwie „v3_poprawiony_2_FINAL_ostateczny.docx” – daj GitHubowi szansę. Pół godziny na konfigurację, a potem tylko commity i spokojna głowa, że historia zmian jest bezpieczna. A Ty? Korzystasz już z gita w pracy projektowej, czy dopiero się przymierzasz? Daj znać w komentarzu.

Ten wpis przygotowałem z myślą o inżynierach, którzy szukają prostych, praktycznych rozwiązań bez zbędnego hype’u. Jeśli podoba Ci się ten tekst, udostępnij go dalej – może akurat Twój kolega z biura też zmaga się z chaosem dokumentacyjnym.

Sprawdź również:

• 10 darmowych alternatyw open-source, które zastąpią Twoje drogie subskrypcje
• Podsumowanie spotkań z AI, pipeline OBS Studio, transkrypcja, baza wiedzy
• Alternatywy dla Obsidiana, Logseq, Notion, Capacities
• Rozmawiaj z Excelem, jak połączyć Codexa z arkuszem kalkulacyjnym
• GitHub jako repozytorium dokumentacji projektowej, wersjonowanie opisów i zestawień