Я ищу программное обеспечение для организации и ведения внутренней документации проектов, спецификаций, требований и т. Д. В настоящее время мы храним всю документацию в виде большого количества файлов MS Word DOC в репозитории контроля версий, что дает нам контроль версий, и это хорошо. Но вы не можете искать эту информацию, создавать ссылки между ними, классифицировать, сотрудничать.
Требования, предпочтения:
- Нулевая установка на стороне клиента (на основе WEB).
- Контроль версий документа.
- Аннотации документов.
- Ссылка на документ.
- Полный поиск (вся документация).
- MS Word (* .doc) импорт \ экспорт.
- WYSIWYG текстовый редактор.
Системы, которые я обнаружил и попробовал до сих пор:
Ответы:
Как насчет Сфинкса ?
Вы пишете свою документацию в reStructuredText (синтаксис похож на Markdown, который использует переполнение стека) в простые текстовые файлы (= легко контролировать версию), а Sphinx выплевывает HTML-страницы.
Двумя наиболее известными пользователями Sphinx (о которых я знаю) являются язык Python и TortoiseHG (см. Ссылки на документацию, созданную Sphinx).
РЕДАКТИРОВАТЬ:
Я только что прочитал, что вы говорите о внутренней документации проекта, а не о документации конечного пользователя.
На мой взгляд, что-то вроде Sphinx также является лучшим способом для внутренней документации (при условии, что вы можете заставить своих аналитиков написать reStructuredText), потому что:
Если Sphinx слишком сложен, есть даже более простой способ: вы можете написать свою документацию в Markdown и использовать Pandoc для создания (например) .rtf, .doc или .pdf файлов (это может сделать намного больше).
Я обнаружил, что Pandoc легче начать, чем Sphinx, но Pandoc не может создавать красивые иерархии меню, такие как Sphinx (как в документации по Python и TortoiseHG, которую я связал выше).
Независимо от того, какие инструменты вы используете, если у вас есть внутренний веб-сервер и сервер сборки, вы можете настроить его так, чтобы сервер сборки генерировал вывод HTML и копировал его на веб-сервер каждый раз, когда кто-то что-то передает в документацию. Таким образом, вашим аналитикам даже не нужно думать о конечном результате, им просто нужно зафиксировать и внести свои изменения.
источник
Ну, вы можете попробовать реализовать вики. В Mediawiki есть все недостающие функции, о которых вы говорите (функции поиска, история версий, ссылки, категоризация). Вам необходимо убедиться, что вы точно знаете, какая версия документации относится к какой версии программного обеспечения, но это можно сделать путем соглашения о включении ссылки на версию или определенной категории в каждую версию, зависящую от версии.
НО: Вы пишете, что у вас есть «аналитики», которые не являются разработчиками (я признаю, я не фанат этого созвездия). Такие люди часто недовольны, когда вы заменяете их инструменты MS Office каким-либо текстовым инструментом, таким как вики. А поскольку MS-Word не является свободным программным обеспечением, я предполагаю, что требование «свободного программного обеспечения» не является обязательным. В этой ситуации лучшим вариантом может стать сервер Sharepoint. Не бесплатно, но AFAIK имеет все функции, которые вы запрашиваете, и документы по-прежнему могут быть созданы с помощью Word, Excel и т. Д.
источник
Всегда лучше держать спецификации и документацию под контролем версий, так как это даст вам наибольшее преимущество, хотя кривая обучения будет немного крутой. В случае двигателя знаний, я рекомендую следующее
Оба имеют минимальные интерфейсы, поддерживают большинство вики-структур, довольно просты в развертывании и обслуживании, поддерживают исправления, имеют хороший редактор WYSIWYG, и вы даже можете хранить свою документацию и спецификации. Если ваши проекты не очень большие, вы можете выбрать любой из вышеперечисленных.
источник
Недавно мы начали использовать Alfresco DMS, которая обладает множеством интересных свойств:
Есть также некоторые недостатки:
Если вы решите дать ему ход, пожалуйста, свяжитесь со мной, чтобы высказать свое мнение.
источник
Другая возможность может быть использовать LaTeX или какой - либо другой текст formater (возможно Texinfo или даже хам ) для документации. Части этого могут быть произведены машиной. Есть некоторые инструменты для преобразования HTML, такие как HeVeA для преобразования LaTeX в HTML. Вы также можете использовать doxygen для генерации документации из структурированных комментариев внутри вашего исходного кода. И рукописные части документации могут (и должны) управляться как исходный код (например, контроль версий и сборка).
источник
Я бы предложил использовать инструмент UML и ERD, в дополнение к вашим документам. Кроме того, вы можете хранить эти документы на ZOHO в ZOHO-Docs , который не является бесплатным, но он чрезвычайно дешев и позволяет выполнять поиск документов.
Какой бы инструмент вы ни использовали в конечном итоге, вам нужно тщательно организовать содержимое документа, чтобы иметь возможность использовать текстовый поиск и получать значимые результаты. Организация содержимого документа вместе с умным и стандартным именованием файлов может очень помочь.
источник