какую систему технической документации онлайн вы бы порекомендовали? [закрыто]

11

цель состоит в том, чтобы иметь систему документации онлайн, с этими основными требованиями:

  • будет в основном использоваться в качестве промежуточного этапа для окончательных технических документов по всем нашим приложениям (которые, вероятно, никогда не будут завершены, хотя:]). Обычно это используется так: у кого-то есть проблема, я исправляю ее и немедленно записываю ее. То, что происходит сейчас, становится неуправляемым: у кого-то есть проблема, я ее исправляю, и я, и кто-то счастливы, но через 2 месяца у кого-то есть такая же проблема, и никто не помнит, что это было за исправление.
  • доступна везде, работает за нашим сервером Apache
  • управление пользователями / группами, позволяющее доступ только для чтения / чтения-записи / доступа администратора
  • формат не так уж важен: подойдет обычный текст, хотя вики-стиль будет лучше
  • дешево или бесплатно

некоторые мои идеи:

  • просто обслуживайте файлы в общей папке или через ssh (минусы: не слишком совместимы с Windows, плюсы: простые, могут быть файлы любого типа)
  • храните его в SCM (svn / git, то же самое, что и выше, но более легкий доступ и контроль доступа)
  • Confluence: мы уже используем Jira, стоит ли Confluence? Как это интегрируется с Jira?
  • что-то другое?

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

documentation Стейн
источник
Документация генерируется из кода (такого как Javadocs), или она написана с нуля, как руководство пользователя, или как некоторая комбинация этих двух?
FrustratedWithFormsDesigner
В основном это скорее руководство пользователя, а не документация по коду (ну, у нас это тоже есть, сгенерированное doxygen, мы можем включить его, но это не первая достопримечательность)
stijn
Я бы отдал немного денег Спольскому.
Работа

Ответы:

11

Я собирался предложить вики

Поскольку Confluence - это вики, я думаю, что использовать его с вашей JIRA - отличная идея. У вас будет преимущество, если вы сможете напрямую связываться с проблемами JIRA и, следовательно, с действующим кодом / документом / любым другим изменением и т. Д.

Ключом к любому репозиторию документов, подобному этому, является аспект навигации. Вы не хотите, чтобы страницы были отключены, трудны для поиска и т. Д. Обдумайте «макет сайта» так же, как для веб-сайта.

Мартейн Вербург
источник
Слияние может, очевидно, экспортировать в различные плоские форматы. Звучит как один из самых простых способов перейти от легко редактируемого к готовому produc.t
2
У нас есть Confluence, где я работаю - мы мигрировали из MediaWiki - и он хорошо работает, выводя в несколько форматов (Word является самым популярным). Но имейте в виду, что его инструменты редактирования WYSIWYG невероятно глючат, а система тегов оставляет желать лучшего, по крайней мере, при нашей установке.
Филипп Реган
+1 для Wiki, я также нашел Trac очень полезным в этом случае, поскольку он интегрируется с SVN, позволяя также делиться файлами.
мы проверили испытание Confluence, и оно будет решением. Кажется, что мы можем сделать гораздо больше, чем нам нужно, но с ним довольно легко работать. Я попробовал Trac пару лет назад, и это было слишком грязно на мой вкус, особенно когда дело дошло до плагинов и т. Д.
stijn