Wszyscy wiedzą, że dobrze udokumentowane tworzenie oprogramowania prowadzi do sukcesu. Zazwyczaj oznacza to jednak, że w dokumencie będą uwzględnione nie tylko zwykły tekst, ale także zawartość binarna, na przykład diagram UML. I słyszałem, że wiele osób tak mówi. System kontroli wersji nie jest odpowiednim miejscem dla plików binarnych. Całkowicie rozumiem i zgadzam się z tym problemem. Zapytałem kilku doświadczonych programistów, gdzie powinno być najlepsze miejsce do przechowywania dokumentów, a odpowiedzią było „wiki”. Wiki jest dobra, ale pomyślałem o innym potencjalnym problemie. W jaki sposób kod źródłowy przechowywany w systemie kontroli wersji może łączyć się z powiązanym dokumentem na wiki? Powiedzmy, że ktoś klonuje repozytorium git lub merkurialne. Jak on / ona może łatwo znaleźć dokument? A może po prostu coś przeoczyłem?
Wiem, że niektóre systemy wiki mają możliwość integracji z systemami kontroli źródła. Ale moje obawy nie dotyczą zdolności integracji. Jeśli sklonowałeś kod źródłowy z repozytorium git i po chwili wsiadasz do pociągu i chcesz kontynuować pracę offline w pociągu (co jest dużą cechą DVCS). Nagle zdajesz sobie sprawę, że nie masz dostępu do dokumentów, ponieważ pracujesz w pociągu offline. Z drugiej strony, jeśli dokument byłby przechowywany w repozytorium git, miałbyś dostęp do dokumentu ze sklonowanym repozytorium.
źródło
Odpowiedzi:
Zamiast pisać dokumenty, pliki PDF i inne rodzaje plików, dlaczego nie uwolnisz pełnego potencjału WIKI jako narzędzia do współpracy? Możesz tam pisać dokumenty, załączać diagramy, a nawet lepiej: jeśli używasz Fitnesse , możesz zamienić swoje strony wiki w naprawdę przydatną i żywą dokumentację, ponieważ mogą one stać się specyfikacją wykonywalną.
Uważaj na to. Dokumenty NIE BĘDĄ PROWADZIĆ DO SUKCESU, ponieważ nie zamienią bzdurnego kodu w dobry. Ale dokumenty są częścią drogi do udanego oprogramowania. Ale tylko część i nie zastąpią dobrych praktyk i dobrych ludzi.
źródło
Ponieważ wiele odpowiedzi wskazuje na Traca jako sugestię, chciałbym zaproponować podobną, ale moim zdaniem lepszą alternatywę: Redmine .
Redmine to rozwiązanie do zarządzania projektami, obejmujące Wiki, repozytorium dokumentów i integrację kontroli wersji. Jest również napisany w Ruby on Rails i według mojego doświadczenia łatwiej jest go rozszerzać i hakować niż Trac.
Ponad wszystko jest naprawdę łatwy w użyciu i łatwo jest go zmusić zespół do korzystania z niego.
Cechy:
Jeśli chodzi o twoje potrzeby offline, nie podoba mi się pomysł zaśmiecania kontroli wersji dokumentami projektowymi. Jestem pewien, że masz powody, by o to pytać, ale tak naprawdę, jak często jesteś offline i potrzebujesz dostępu do dokumentów projektowych? Są szanse, że to naprawdę przypadek narożny.
źródło
Niektóre strony wiki (np. Ikiwiki ) mają możliwość przechowywania swoich danych w Git, jak wspomniałeś. Biorąc to pod uwagę, możesz połączyć dokumentację jako podmoduł Git w swoim regularnym repozytorium źródłowym.
Przy powyższej konfiguracji pobranie źródła i aktualizacja podmodułów spowoduje pobranie najnowszej kopii dokumentacji. W trybie offline możesz edytować każdy z nich do woli. Po powrocie do sieci oba można odepchnąć z powrotem do dowolnej udostępnionej lokalizacji, z której korzystasz.
Niezręczne jest to, że za każdym razem, gdy dokumentacja jest aktualizowana (nawet przez interfejs sieciowy Ikiwiki), musisz także zaktualizować odpowiedni podmoduł w repozytorium źródłowym Git. Można to jednak łatwo zautomatyzować.
źródło
Sensowne jest przechowywanie dokumentacji w tym samym repozytorium, co kod źródłowy. Sfinks wydaje mi się dobrą opcją.
źródło
Trac zapewnia interfejs do Subversion, zintegrowaną Wiki i wygodne funkcje raportowania. http://trac.edgewall.org/
Ale nie wiem o twoim zainstalowanym stosie.
źródło
Nie próbowałbym dostosować się do pracy offline. Korzystałbym z zasobów, które sprawiają, że najłatwiej jest pracować dla wszystkich. Na przykład, jeśli piszesz kod PHP, sugerowałbym użycie wbudowanej dokumentacji, którą można wygenerować przez PHPDocumentor . Można go wygenerować w dowolnym miejscu i jest wtyczka do Traca . Następnie w trybie online lub offline masz dostęp do dokumentacji dość szybko.
Kluczem jest użyteczność. Jeśli będzie trudny do utrzymania, zacznie cierpieć. Kiedy zaczyna cierpieć, jakość dokumentacji spada. Kiedy tak się dzieje, ludzie zaczynają narzekać, a potem wszystko idzie w dół.
źródło
Używanie wiki do przechowywania dokumentacji ma dla mnie sens.
Veracity jest przykładem DVCS, który pozwala na ściślejszą integrację treści wiki i kodu źródłowego.
źródło