Oprogramowanie do organizowania i utrzymywania dokumentacji projektowej, specyfikacji? [Zamknięte]

15

Szukam oprogramowania do organizowania i utrzymywania wewnętrznej dokumentacji projektów, specyfikacji, wymagań itp. Obecnie przechowujemy całą dokumentację jako wiele plików MS Word DOC w repozytorium kontroli źródła, co daje nam kontrolę wersji i to miło. Ale nie możesz wyszukiwać tych informacji, tworzyć między nimi łączy, kategoryzować, współpracować.

Wymagania, preferencje:

  • Brak instalacji po stronie klienta (oparty na sieci).
  • Kontrola wersji dokumentu.
  • Dokumenty adnotacji.
  • Łączenie dokumentów.
  • Pełne wyszukiwanie (cała dokumentacja).
  • Import / eksport MS Word (* .doc).
  • Edytor tekstu WYSIWYG.

Systemy, które odkryłem i wypróbowałem do tej pory:

Alex Burtsev
źródło
Jaki masz dokumentację projektu (diagramy tekstowe, graficzne, UML, harmonogramy, specyfikacje tekstowe, historie użytkowników itp.)? Ile osób musi to utrzymywać? Czy musi być zsynchronizowany z określonymi wersjami / wersjami Twojego kodu źródłowego?
Doc Brown
@DocBrown, 95% tekstowe, 3-5 osób napisze to. Zsynchronizowałem się z wersjami oprogramowania, ale nie wprowadziłem wersji kodu źródłowego.
Alex Burtsev,
XWiki wygląda na fajne rozwiązanie, jest bezpłatne, ładnie integruje się z MS Office.
Alex Burtsev,
1
Jest to bardzo bliskie byciu duplikatem Jakiego programu używasz do pisania dokumentacji technicznej? wiele odpowiedzi jest podobnych, ale istnieją lepsze argumenty przeciwko używaniu wiki do takiej dokumentacji.
Mark Booth,
Co powiesz na oprogramowanie do zarządzania wiedzą, takie jak PHPKB ? Nie jest darmowy, ale wydaje się, że bardzo dobrze służy twojemu celowi.
Anirudh Srivastava

Odpowiedzi:

6

Co powiesz na coś takiego jak Sfinks ?

Piszecie swoją dokumentację w reStructuredText (składnia jest podobna do Markdown, której używa przepełnienie stosu) do zwykłych plików tekstowych (= łatwa do kontroli wersji), a Sphinx wyrzuca strony HTML.

Dwaj najwybitniejsi użytkownicy Sfinksa (o których wiem) to język Python i TortoiseHG (zobacz linki do dokumentacji wygenerowanej przez Sfinksa).


EDYTOWAĆ:

Właśnie przeczytałem, że mówisz o dokumentacji wewnętrznej projektu, a nie dokumentacji użytkownika końcowego.
Moim zdaniem coś takiego jak Sphinx jest najlepszym sposobem na wewnętrzną dokumentację (pod warunkiem, że możesz poprosić analityków o napisanie reStructuredText), ponieważ:

  1. Możesz łatwo kontrolować wersję dokumentów (a różnice w plikach tekstowych zajmują o wiele, wiele mniej miejsca niż pliki binarne, takie jak .doc lub .pdf).
  2. Jeśli programista chce ładnego, czytelnego pliku .doc lub .pdf, może go utworzyć ze Sphinx ze źródeł.

Jeśli Sphinx jest zbyt skomplikowany, istnieje jeszcze prostszy sposób: możesz napisać swoją dokumentację w Markdown i użyć Pandoc do utworzenia (na przykład) plików .rtf, .doc lub .pdf (może to zrobić znacznie więcej).
Uważam, że Pandoc jest łatwiejszy do rozpoczęcia niż Sphinx, ale Pandoc nie może tworzyć ładnych hierarchii menu takich jak Sphinx (jak w dokumentacji Pythona i TortoiseHG, które podlinkowałem powyżej).

Bez względu na to, z którego narzędzia korzystasz, jeśli masz wewnętrzny serwer WWW i serwer kompilacji, możesz go skonfigurować tak, aby serwer kompilacji generował dane wyjściowe HTML i kopiował je na serwerze internetowym za każdym razem, gdy ktoś popycha coś do dokumentacji. Więc twoi analitycy nie muszą nawet myśleć o ostatecznym wyniku, muszą jedynie zatwierdzić i naciskać na swoje zmiany.

Christian Specht
źródło
Wygląda na to, że po prostu generuje HTML, wtedy będę musiał opublikować go na serwerze WWW
Alex Burtsev,
1
@AlexBurtsev: Jeśli chcesz być publiczny, to tak. Z drugiej strony - teraz używasz plików Word .doc, więc musisz je również umieścić na serwerze internetowym, jeśli chcesz, aby były publiczne.
Christian Specht
Zauważam, że Sphinx ma ścieżkę „wyjście do pliku PDF”.
Robert Harvey
@ChristianSpecht, Wiki i Wordpress mają wtyczki do importowania plików Word Doc.
Alex Burtsev,
@AlexBurtsev: Nie jestem pewien, czy zrozumiałem, co chcesz zrobić z dokumentacją. Jeśli chcesz umieścić go w Internecie, potrzebujesz jakiegoś serwera WWW, bez względu na to, czy używasz Sphinx, Wordpress, .doc download lub czegoś innego. Jeśli potrzebujesz rozpowszechniać dokumentację za pomocą oprogramowania do zawijania, możesz użyć Sphinx do generowania plików PDF lub plików pomocy Windows.
Christian Specht
5

Możesz spróbować wdrożyć Wiki. Mediawiki ma wszystkie brakujące funkcje, o których mówisz (funkcje wyszukiwania, historia wersji, linki, kategoryzacja). Musisz upewnić się, że dokładnie wiesz, która wersja dokumentacji należy do której wersji oprogramowania, ale można tego dokonać, umieszczając odniesienie do wersji lub określoną kategorię w każdym artykule zależnym od wersji.

ALE: Piszesz, że masz „analityków”, którzy nie są programistami (przyznaję, nie jestem fanem tej konstelacji). Tacy ludzie często nie są zadowoleni, gdy zamieniają swoje narzędzia MS Office na jakieś narzędzie tekstowe, takie jak Wiki. A ponieważ MS-Word nie jest wolnym oprogramowaniem, myślę, że wymóg „wolnego oprogramowania” nie jest tak naprawdę koniecznością. W tej sytuacji lepszym rozwiązaniem może być serwer Sharepoint. Nie jest darmowy, ale AFAIK ma wszystkie funkcje, o które prosisz, a dokumenty można nadal tworzyć za pomocą Worda, Excela itp.

Doktor Brown
źródło
1
Mamy już serwer SharePoint, ale programiści go nie lubią i nie chcą go używać (sam jestem programistą). Chcemy czegoś, w czym możemy łatwo znaleźć potrzebne informacje. Informacje podzielone na kategorie i powiązane.
Alex Burtsev,
@AlexBurtsev: Sam nigdy nie korzystałem z serwera Sharepoint, ale miałem wrażenie, że Sharepoint zapewnia wszystkie te funkcje, które opisujesz. Ale jeśli wolisz Wiki, Mediawiki będzie dla ciebie odpowiednie. Podejmiesz jednak trochę wysiłku, aby go zainstalować, zdefiniować zarys struktury, a także zdefiniować konwencje, jak go używać / nie używać.
Doc Brown
Obecnie wypróbowuję XWiki pod kątem integracji z MS Office
Alex Burtsev
@DocBrown - SharePoint jest okropny. Jest to nieintuicyjne, kompletny labirynt kart i podkart i nie utrzymuje właściwej kontroli wersji. Każdy, kto go użyje, lepiej zrzuci wszystkie swoje dokumenty do wspólnego katalogu na serwerze wewnętrznym. Wiki jest zwykle drogą do tego typu rzeczy.
Wielomian
2

Zawsze lepiej jest zachować specyfikację i dokumentację pod kontrolą wersji, ponieważ zapewniłoby to największy wpływ, chociaż krzywa uczenia się byłaby nieco stroma. W przypadku silnika wiedzy polecam następujące

  1. Trac - Łatwy w użyciu system śledzenia błędów i silnik wiedzy. Napisane w Pythonie i rozszerzalne, będziesz gotowy do działania za kilka minut
  2. MoinMoin - pełnoprawny silnik wiki. Znów Python z wieloma funkcjami

Oba mają minimalne interfejsy, obsługują większość struktur wiki, dość łatwe do wdrożenia i utrzymania, obsługują wersje, mają dobry edytor WYSIWYG, a nawet możesz zachować swoją dokumentację i specyfikację. Jeśli twoje projekty nie są naprawdę ogromne, możesz wybrać dowolną z powyższych opcji.

Ubermensch
źródło
2

Niedawno zaczęliśmy korzystać z Alfresco DMS, który ma wiele interesujących właściwości:

  • Bardzo prosta instalacja
  • Ma wbudowany indeksator do szybkiego przeszukiwania stosów dokumentów
  • Umożliwia przepływ pracy, grupy i, w razie potrzeby, określony dostęp do dokumentów przez klientów
  • Otwarte źródło
  • Aktywna społeczność
  • Integracja z LDAP / AD / SSO
  • Obsługuje wiele różnych dokumentów

Istnieją również pewne wady:

  • Interfejs użytkownika nie zawsze jest intuicyjny
  • Nie jest to tak naprawdę wiki, więc jednoczesna współpraca nad jednym dokumentem może być nieco krucha

Jeśli zdecydujesz się na huśtawkę, skontaktuj się ze mną ze swoimi opiniami.

Dibbeke
źródło
0

Inną możliwością może być użycie LaTeX lub innego formater tekstu (może texinfo lub nawet prostak ) dla dokumentacji. Części można wygenerować maszynowo. Istnieje kilka narzędzi do konwersji HTML, takich jak HeVeA do konwersji LaTeX na HTML. Możesz również użyć doxygen do generowania dokumentacji na podstawie uporządkowanych komentarzy w kodzie źródłowym. A ręcznie napisane części dokumentacji mogą (i powinny) być zarządzane jako kod źródłowy (np. Kontrola wersji i kompilacja).

Basile Starynkevitch
źródło
Nie mówię o dokumentacji produktu (pomoc, instrukcja). Mówię o specyfikacji oprogramowania, wymaganiach biznesowych.
Alex Burtsev,
Możesz napisać specyfikację oprogramowania lub dowolny dokument techniczny w LaTeX, aw niektórych kręgach jest to powszechną praktyką.
Basile Starynkevitch,
2
LaText w jakiś sposób przypomina mi * NIX, a nasi analitycy nigdy nie gromadzą takich systemów operacyjnych -), żyją w świecie Windows i nie zgodzą się na coś trudniejszego niż Word do wprowadzania tekstu.
Alex Burtsev,
-2

Sugeruję użycie narzędzia UML i ERD oprócz twoich dokumentów. Ponadto możesz przechowywać te dokumenty w ZOHO w ZOHO-Docs , co nie jest darmowe, ale jest wyjątkowo tanie i umożliwia wyszukiwanie dokumentów.

Niezależnie od tego, jakiego narzędzia użyjesz, musisz starannie uporządkować zawartość dokumentu, aby móc korzystać z wyszukiwania tekstowego i uzyskiwać znaczące wyniki. Organizacja treści dokumentu wraz ze sprytnym i standardowym nazewnictwem plików może bardzo pomóc.

Bez szans
źródło