Czy strony wiki naprawdę są odpowiednie do przechowywania dokumentów w celu opracowania oprogramowania? [Zamknięte]

18

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.

Edison Chuang
źródło
3
FYI: Wiki to nie skrót, to hawajskie słowo oznaczające „szybki”.
Jörg W Mittag
Fakt, że dokumentacja obejmuje pliki binarne, nie jest tak naprawdę dobrym powodem, aby unikać przechowywania jej w systemie kontroli wersji. VCS może łatwo radzić sobie z plikami binarnymi. A jeśli przechowujesz go w VCS swojego projektu, masz tę zaletę, że możesz rozgałęzić swoją dokumentację podczas rozgałęziania projektu.
JW01
Jeśli chodzi o pracę w trybie offline: Brute-force rozwiązaniem jest po prostu pobranie stron, które chcesz za pomocą czytnika offline. Bardziej eleganckie jest jakoś sklonowanie całej wiki, jeśli jest to praktyczne (np. Skopiowanie bazowej bazy danych i posiadanie własnej instalacji wiki). Wiki oparte na VCS to jeszcze bardziej eleganckie rozwiązanie. Często pracuję offline i zazwyczaj wystarczy pobrać strony, których potrzebuję regularnie.
sleske

Odpowiedzi:

16

Czy WIKI naprawdę nadaje się do przechowywania dokumentów w celu opracowania oprogramowania?

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ą.

Wszyscy wiedzą, że dobrze udokumentowane tworzenie oprogramowania prowadzi do sukcesu

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.

Fernando
źródło
8

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:

  • Obsługa wielu projektów
  • Elastyczna kontrola dostępu oparta na rolach
  • Elastyczny system śledzenia problemów
  • Wykres Gantta i kalendarz
  • Zarządzanie wiadomościami, dokumentami i plikami
  • Kanały i powiadomienia e-mail
  • Wiki projektu
  • Fora projektów
  • Śledzenie czasu
  • Niestandardowe pola dla problemów, wpisów czasu, projektów i użytkowników
  • Integracja SCM (SVN, CVS, Git, Mercurial, Bazaar i Darcs)
  • Tworzenie problemu przez e-mail
  • Obsługa wielu uwierzytelnień LDAP
  • Wsparcie dla samodzielnej rejestracji użytkownika
  • Obsługa wielu języków
  • Obsługa wielu baz danych

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.

Vitor Py
źródło
+1 Korzystam z Redmine w pracy i to naprawdę świetny system.
Luiz Damim
5

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ć.

Greg Hewgill
źródło
Ciekawy. Czy istnieje różnica między umieszczeniem dokumentu w repozytorium git a przechowywaniem dokumentu za pośrednictwem ikiwiki?
Edison Chuang
1
@Edison Chuang: Nie, nie ma. W rzeczywistości, biorąc pod uwagę klon repozytorium ikiwiki, możesz edytować strony za pomocą wybranego edytora tekstu (nie musisz używać gównianego okna do wprowadzania tekstu opartego na przeglądarce). Możesz nawet mieć różne gałęzie wiki, aby zachować migawkę starszej dokumentacji lub cokolwiek innego.
Greg Hewgill
Wygląda na to, że dokument może być przechowywany w systemie kontroli wersji bez żadnych problemów, nawet jeśli pliki binarne. Deweloper może po prostu użyć narzędzi takich jak ikiwiki do konwersji stron wiki na strony HTML na żądanie.
Edison Chuang
+1 dla silnika wiki Ikiwiki; silnik wiki Hatta jest podobny pomysł repozytoria Mercurial.
David Cary,
ISTR Fitnesse przechowuje również swoje strony wiki jako pliki tekstowe, więc one również mogą być przechowywane w systemie kontroli wersji, jeśli chcesz. Chociaż jego głównym celem jest testowanie, nie ma powodu, aby nie używać go jako systemu wiki ogólnego przeznaczenia również w dokumentacji.
Jules
4

Sensowne jest przechowywanie dokumentacji w tym samym repozytorium, co kod źródłowy. Sfinks wydaje mi się dobrą opcją.

Brecht Machiels
źródło
2

Trac zapewnia interfejs do Subversion, zintegrowaną Wiki i wygodne funkcje raportowania. http://trac.edgewall.org/
Ale nie wiem o twoim zainstalowanym stosie.

Chiron
źródło
I ładny interfejs do Mercurial. I jest to wyjątkowo łatwe do zhakowania.
Frank Shearar
0

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ół.

Chuck Burgess
źródło
-1

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.

Jace Browning
źródło