Программное обеспечение для организации и ведения проектной документации, спецификации? [закрыто]

15

Закрыто. Этот вопрос не по теме . В настоящее время он не принимает ответы.

Хотите улучшить этот вопрос? Обновите вопрос, чтобы он соответствовал теме разработки программного обеспечения стека Exchange.

Закрыто 6 лет назад .

Я ищу программное обеспечение для организации и ведения внутренней документации проектов, спецификаций, требований и т. Д. В настоящее время мы храним всю документацию в виде большого количества файлов MS Word DOC в репозитории контроля версий, что дает нам контроль версий, и это хорошо. Но вы не можете искать эту информацию, создавать ссылки между ними, классифицировать, сотрудничать.

Требования, предпочтения:

Нулевая установка на стороне клиента (на основе WEB).
Контроль версий документа.
Аннотации документов.
Ссылка на документ.
Полный поиск (вся документация).
MS Word (* .doc) импорт \ экспорт.
WYSIWYG текстовый редактор.

Системы, которые я обнаружил и попробовал до сих пор:

— Алекс Бурцев
источник

Какой вид документации у вас есть (текстовые, графические, UML-диаграммы, графики, текстовые спецификации, пользовательские истории и т. Д.)? Сколько людей должны поддерживать это? Должен ли он быть синхронизирован с конкретными версиями / ревизиями вашего исходного кода?

— Док Браун

@DocBrown, 95% текстовых, 3-5 человек будут писать. Я синхронизируюсь с версиями программных продуктов, но не с версиями исходного кода.

— Алексей Бурцев

XWiki выглядит как хорошее решение, оно бесплатное, оно прекрасно интегрируется с MS Office.

— Алексей Бурцев

1

Это очень похоже на дубликат какой программы вы используете для написания технической документации? и многие из ответов похожи, но есть лучшие аргументы против использования вики для такой документации.

— Марк Бут

Как насчет программного обеспечения для управления знаниями, как PHPKB ? Это не бесплатно, но, кажется, служит вашей цели очень хорошо.

— Анирудх Шривастава

6

Как насчет Сфинкса ?

Вы пишете свою документацию в reStructuredText (синтаксис похож на Markdown, который использует переполнение стека) в простые текстовые файлы (= легко контролировать версию), а Sphinx выплевывает HTML-страницы.

Двумя наиболее известными пользователями Sphinx (о которых я знаю) являются язык Python и TortoiseHG (см. Ссылки на документацию, созданную Sphinx).

РЕДАКТИРОВАТЬ:

Я только что прочитал, что вы говорите о внутренней документации проекта, а не о документации конечного пользователя.
На мой взгляд, что-то вроде Sphinx также является лучшим способом для внутренней документации (при условии, что вы можете заставить своих аналитиков написать reStructuredText), потому что:

Вы можете легко управлять версиями документов (а различия текстовых файлов занимают намного больше места, чем двоичные файлы, такие как .doc или .pdf).
Если разработчику нужен хороший читаемый файл .doc или .pdf, он может создать его с помощью Sphinx из исходников.

Если Sphinx слишком сложен, есть даже более простой способ: вы можете написать свою документацию в Markdown и использовать Pandoc для создания (например) .rtf, .doc или .pdf файлов (это может сделать намного больше).
Я обнаружил, что Pandoc легче начать, чем Sphinx, но Pandoc не может создавать красивые иерархии меню, такие как Sphinx (как в документации по Python и TortoiseHG, которую я связал выше).

Независимо от того, какие инструменты вы используете, если у вас есть внутренний веб-сервер и сервер сборки, вы можете настроить его так, чтобы сервер сборки генерировал вывод HTML и копировал его на веб-сервер каждый раз, когда кто-то что-то передает в документацию. Таким образом, вашим аналитикам даже не нужно думать о конечном результате, им просто нужно зафиксировать и внести свои изменения.

— Кристиан Шпехт
источник

Похоже, он просто генерирует HTML, тогда мне придется опубликовать его на веб-сервере

— Алексей Бурцев

1

@AlexBurtsev: Если вы хотите, чтобы это было публично, тогда да. С другой стороны - теперь вы используете файлы Word .doc, поэтому вы должны также разместить их на веб-сервере, если вы хотите, чтобы они были общедоступными.

— Кристиан Шпехт

Я отмечаю, что у Sphinx есть путь «вывода в PDF».

— Роберт Харви

@ChristianSpecht, Wiki и Wordpress имеют плагины для импорта файлов Word Doc.

— Алексей Бурцев

@AlexBurtsev: Я не уверен, понял ли я, что вы хотите сделать с документацией. Если вы хотите разместить его в Интернете, то вам нужен какой-то веб-сервер, независимо от того, используете ли вы Sphinx, Wordpress, загрузку .doc или что-то еще. Если вам нужно распространять документацию с помощью программного обеспечения для термоусадочной упаковки, вы можете использовать Sphinx для создания PDF-файлов или файлов справки Windows.

— Кристиан Шпехт

5

Ну, вы можете попробовать реализовать вики. В Mediawiki есть все недостающие функции, о которых вы говорите (функции поиска, история версий, ссылки, категоризация). Вам необходимо убедиться, что вы точно знаете, какая версия документации относится к какой версии программного обеспечения, но это можно сделать путем соглашения о включении ссылки на версию или определенной категории в каждую версию, зависящую от версии.

НО: Вы пишете, что у вас есть «аналитики», которые не являются разработчиками (я признаю, я не фанат этого созвездия). Такие люди часто недовольны, когда вы заменяете их инструменты MS Office каким-либо текстовым инструментом, таким как вики. А поскольку MS-Word не является свободным программным обеспечением, я предполагаю, что требование «свободного программного обеспечения» не является обязательным. В этой ситуации лучшим вариантом может стать сервер Sharepoint. Не бесплатно, но AFAIK имеет все функции, которые вы запрашиваете, и документы по-прежнему могут быть созданы с помощью Word, Excel и т. Д.

— Док Браун
источник

1

У нас уже есть сервер SharePoint, но разработчикам он не нравится, и мы не хотим его использовать (я сам разработчик). Мы хотим что-то, где мы можем легко найти нужную нам информацию. Информация, которая классифицирована и связана.

— Алексей Бурцев

@AlexBurtsev: Я никогда не использовал сам сервер Sharepoint, но у меня сложилось впечатление, что Sharepoint предоставляет все те функции, которые вы описывали. Но если вы предпочитаете вики, Mediawiki подойдет вам. Тем не менее, вы предпримете некоторые первоначальные усилия для его установки, определите структуру структуры, а также определите некоторые соглашения, как использовать / не использовать ее.

— Док Браун

В настоящее время я пробую XWiki для его интеграции с MS Office

— Алекс Бурцев

@DocBrown - SharePoint ужасен. Это не интуитивно понятно, полный лабиринт вкладок и вложенных вкладок, и не поддерживает должного контроля версий. Любой, кто использует это, будет лучше выгрузить все свои документы в общий каталог на внутреннем сервере. Вики - это, как правило, способ пойти на подобные вещи.

— Полином

2

Всегда лучше держать спецификации и документацию под контролем версий, так как это даст вам наибольшее преимущество, хотя кривая обучения будет немного крутой. В случае двигателя знаний, я рекомендую следующее

Trac - Простая в использовании система отслеживания ошибок и система знаний. Написанный на Python и расширяемый, вы сможете начать работу через несколько минут
MoinMoin - полноценный вики-движок. Снова Python с большим количеством функций

Оба имеют минимальные интерфейсы, поддерживают большинство вики-структур, довольно просты в развертывании и обслуживании, поддерживают исправления, имеют хороший редактор WYSIWYG, и вы даже можете хранить свою документацию и спецификации. Если ваши проекты не очень большие, вы можете выбрать любой из вышеперечисленных.

— Ubermensch
источник

2

Недавно мы начали использовать Alfresco DMS, которая обладает множеством интересных свойств:

Очень простая установка
Имеет встроенный индексатор для быстрого поиска по кучам документов
Позволяет рабочим процессам, группам и, если необходимо, конкретному доступу к документам клиентов
Открытый источник
Активное сообщество
Интеграция LDAP / AD / SSO
Обрабатывает много разных документов

Есть также некоторые недостатки:

Пользовательский интерфейс не всегда интуитивно понятен
Это не совсем вики, поэтому совместная совместная работа над одним документом может быть немного хрупкой

Если вы решите дать ему ход, пожалуйста, свяжитесь со мной, чтобы высказать свое мнение.

— Dibbeke
источник

0

Другая возможность может быть использовать LaTeX или какой - либо другой текст formater (возможно Texinfo или даже хам ) для документации. Части этого могут быть произведены машиной. Есть некоторые инструменты для преобразования HTML, такие как HeVeA для преобразования LaTeX в HTML. Вы также можете использовать doxygen для генерации документации из структурированных комментариев внутри вашего исходного кода. И рукописные части документации могут (и должны) управляться как исходный код (например, контроль версий и сборка).

— Василий Старынкевич
источник

Я не говорю о документации программного продукта (справка, руководство). Я говорю о спецификации программного обеспечения, бизнес-требованиях.

— Алексей Бурцев

Вы можете написать спецификацию программного обеспечения или любой технический документ в LaTeX, и в некоторых кругах это обычная практика.

— Василий Старынкевич

2

LaText чем-то напоминает мне * NIX, и наши аналитики никогда не следят за такими ОС -), они живут в мире Windows и не согласятся с чем-то более сложным, чем Word для ввода текста.

— Алексей Бурцев

-2

Я бы предложил использовать инструмент UML и ERD, в дополнение к вашим документам. Кроме того, вы можете хранить эти документы на ZOHO в ZOHO-Docs , который не является бесплатным, но он чрезвычайно дешев и позволяет выполнять поиск документов.

Какой бы инструмент вы ни использовали в конечном итоге, вам нужно тщательно организовать содержимое документа, чтобы иметь возможность использовать текстовый поиск и получать значимые результаты. Организация содержимого документа вместе с умным и стандартным именованием файлов может очень помочь.

— Без шансов
источник