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:
Odpowiedzi:
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ż:
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.
źródło
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.
źródło
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
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.
źródło
Niedawno zaczęliśmy korzystać z Alfresco DMS, który ma wiele interesujących właściwości:
Istnieją również pewne wady:
Jeśli zdecydujesz się na huśtawkę, skontaktuj się ze mną ze swoimi opiniami.
źródło
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).
źródło
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.
źródło