jaki system dokumentacji technicznej online poleciłbyś? [Zamknięte]

11

celem jest posiadanie systemu dokumentacji online z tymi głównymi wymaganiami:

  • będą wykorzystywane głównie jako etap pośredni dla końcowych dokumentów technicznych wszystkich naszych aplikacji (które prawdopodobnie nigdy się nie zakończą:]). Zwykle byłby używany w ten sposób: ktoś ma problem, naprawiam go i natychmiast zapisuję. To, co się teraz dzieje, staje się niemożliwe do rozwiązania: ktoś ma problem, naprawiam go, zarówno ja, jak i ktoś, jesteśmy szczęśliwi, ale 2 miesiące później ktoś ma ten sam problem i nikt nie pamięta, co to była poprawka.
  • dostępne z dowolnego miejsca, działające za naszym serwerem Apache
  • zarządzanie użytkownikami / grupami, umożliwiające dostęp tylko do odczytu / odczyt-zapis / administrator
  • format nie jest zbyt ważny: wystarczy zwykły tekst, ale styl wiki byłby ładniejszy
  • tanie lub darmowe

kilka moich pomysłów:

  • po prostu udostępniaj pliki w udziale plików lub przez ssh (wady: niezbyt dające się kopiować w systemie Windows, zalety: proste, może być dowolnego typu pliku)
  • trzymaj go w SCM (svn / git, idem jak wyżej, ale łatwiejszy dostęp i kontrola dostępu)
  • Confluence: korzystamy już z Jiry, czy Confluence jest tego warte? Jak integruje się z Jira?
  • coś innego?

Nie wahaj się komentować lub podzielić się swoimi doświadczeniami z innymi systemami.

stijn
źródło
Czy dokumentacja jest generowana z kodu (takiego jak Javadocs), czy też jest tworzona od zera, jako przewodnik użytkownika, czy też jako kombinacja tych dwóch?
FrustratedWithFormsDesigner
to głównie podręcznik użytkownika, a nie dokumentacja kodu (no cóż, my też to mamy, generowane przez doxygen, możemy to uwzględnić, ale nie jest to pierwszy punkt zainteresowania)
stijn
Oddałbym trochę gotówki Spolskiemu.
Job

Odpowiedzi:

11

Chciałem zaproponować Wiki

Ponieważ Confluence to wiki, myślę, że używanie jej z JIRA to doskonały pomysł. Będziesz miał tę zaletę, że będziesz w stanie bezpośrednio związać się z problemami JIRA, a zatem faktycznym kodem / dokumentem / jakąkolwiek zmianą itp.

Kluczem do każdego repozytorium dokumentów kodu takiego jak ten jest aspekt nawigacji. Nie chcesz stron, które są rozłączone, trudne do znalezienia itp. Zastanów się nad „układem strony”, podobnie jak w przypadku witryny internetowej.

Martijn Verburg
źródło
Konfluencja może najwyraźniej eksportować w różnych płaskich formatach. Brzmi jak jeden z najłatwiejszych sposobów przejścia od łatwo edytowalnego do gotowego produc.t
2
Mamy Confluence tam, gdzie pracuję - przeprowadziliśmy migrację z MediaWiki - i robi dobrą robotę, wysyłając dane do wielu formatów (Word jest najbardziej popularny). Ale ostrzegamy, że jego narzędzia edycyjne WYSIWYG są bardzo wadliwe, a system tagowania pozostawia wiele do życzenia, przynajmniej w przypadku naszej instalacji.
Philip Regan,
+1 dla Wiki, znalazłem również Traca bardzo przydatnego w tym przypadku, ponieważ integruje się on z SVN, umożliwiając również udostępnianie plików.
sprawdziliśmy test Confluence i to będzie rozwiązanie. Wydaje się, że jesteśmy w stanie zrobić o wiele więcej, niż potrzebujemy, ale dość łatwo jest z nim pracować. Próbowałem Traca kilka lat temu i było to trochę zbyt niechlujne jak na mój gust, szczególnie jeśli chodzi o wtyczki itp.
stijn 21.01.11