Biorąc pod uwagę projekt, który mam zamiar rozpocząć, zostanie sporządzona dokumentacja.Dokumentacja i kontrola wersji
Jaka jest najlepsza praktyka w tym zakresie?
Czy dokumenty powinny zawierać kod i aktywa, czy też powinien istnieć osobny magazyn dokumentacji?
Edit
chciałbym wiki ale muszę drukować dokumenty itd ... Jest to projekt uniwersytecki.
To naprawdę zależy od Twojego zespołu. Gdzie pracuję, przechowujemy dokumentację na wiki, która jest połączona ze stroną naszego zespołu. W celu dostarczenia dokumentacji, wiki można wyeksportować i uruchomić za pomocą parsera, który "rozwija" wygląd i działanie dokumentacji do celów klienta.
Przechowywanie dokumentacji z kodem (zwykle w źródłowym repozytorium) nie jest złym pomysłem. Tylko pamiętaj, aby je rozdzielić. Na przykład zachowaj folder docs, który znajduje się na tym samym poziomie co folder src w repozytorium. W ten sposób możesz szybko wysłać bieżącą dokumentację, możesz łatwo śledzić poprawki, a każdy nowy projekt może od razu wskoczyć bez konieczności odwiedzania wielu lokalizacji w celu uzyskania informacji.
Dobra uwaga na temat przechowywania dokumentów w ich własnym folderze. –
Przechowywanie w pozycji źródłowej jest w porządku.
Jeśli piszesz wersjonowaną dokumentację użytkownika związaną z każdą wersją produktu, warto umieścić dokumentację w kontroli źródła wraz z powiązaną wersją produktu.
Jeśli piszesz wewnętrzną dokumentację dla programistów, skorzystaj z automatycznej dokumentacji wewnętrznego kodu źródłowego (javadoc, doxygen, adnotacje .net, itp.) Do dokumentacji na poziomie źródłowym i do strony projektu dla dokumentacji poziomu projektu.
Myślę, że większość z nas w branży nie przestrzega najlepszych praktyk i oczywiście zależy również od twojej sytuacji.
W zwinnym środowisku, w którym miałbyś bardzo powtarzalny proces uwalniania, będziesz chciał "podróżować światłem". W tym konkretnym przypadku sugestia Jason'a o oddzielnej Wiki naprawdę działa świetnie.
W modelu z opadającą wodą/wielkim wybuchem, będziesz mieć lepszą możliwość aktualizacji przyzwoitej dokumentacji przy każdym nowym wydaniu. Ponadto będziesz musiał jasno udokumentować, która wersja wymagań została uzgodniona i mieć mnóstwo dokumentacji dla każdej drobnej zmiany, którą robisz w stosunku do wymagań (ze względu na efekty, jakie ma ona na kolejne etapy). Często, jeśli dokumentacja może żyć razem z wersją kontrolowanego kodu źródłowego, jest najlepsza.
Czy korzystasz z jakiejkolwiek auto-dokumentacji lub czy jest ona całkowicie ręczna? Zakładając, że używasz systemu auto-dokumentacji, dokumentacja jest generowana mniej więcej w locie i stanowi część samego kodu.
Dla mnie (zakładając, że jest to możliwe przy użyciu dowolnego kodu, którego używasz), byłaby to preferowana metoda postępowania z nim, ponieważ nie musiałbyś w ogóle utrzymywać źródła dokumentacji.
To interesujące pytanie - w zasadzie to, co mówią inni, jest poprawne w odniesieniu do wygenerowanej dokumentacji, plików źródłowych i szablonów/etc.powinny być przechowywane w kontroli źródła i generowane podczas procesu kompilacji.
W zakresie wymagań/specyfikacji/itp. dokumentacja, pracowałem w obie strony, a ja bardzo wolę używać SharePoint lub portalu Wiki/dokumentu, który jest przeznaczony do udostępniania/porównywania dokumentów. Powodem jest to, że większość osób spoza firmy deweloperskiej nie czuje się komfortowo w pracy z systemami kontroli kodu źródłowego i nie uzyskujesz żadnych korzyści inteligentnego scalania, jeśli używasz formatu binarnego, takiego jak Word. Poza tym miło jest mieć dostęp do Internetu, dzięki czemu możesz odwoływać się i pracować nad dokumentami w rozproszonym zespole bez konieczności instalowania dodatkowego oprogramowania.
Oto 2017 podsumowanie opcji i doświadczenie:
package-info.java są niedostatecznie wykorzystane.README.md) - dobry sposób połowę roztworu z korzyści kontroli wersji. Jeśli pojedynczy plik nie wystarcza, rozważ folder doc/. Jedyną wadą tego, co widziałem, jest to, czy można uzyskać pomocną grafikę pomocniczą (na przykład pliki png) i ryzyko wzdrygnięcia repozytorium.
sukces GitHub jest w dużej mierze dzięki jego README.md znajdujących się w katalogu głównym projektu.
Czy jest to dokumentacja na poziomie użytkownika lub dokumentacja dla programistów? – nall
To wszystko. Niestety, to projekt uniwersytecki. – Finglas
Dokumenty są napisane w pakiecie Office jako dokumenty online i są mieszanką treści generowanych ręcznie i automatycznie. – Finglas