2008-09-19 2 views
4

Очевидным ответом является «внутренняя вики». Каковы преимущества и недостатки вики, используемые для документации по программному обеспечению? Любые другие предложения? Что вы используете для документации по вашему программному обеспечению?Каков наилучший способ хранения документации по программному обеспечению?

Loren Segal - К сожалению, у нас нет поддержки какого-либо инструмента doc для компиляции информации из комментариев исходного кода, но я согласен, что это лучший способ хранения технической документации. Мой вопрос касался всех типов документации - от типа sysadmin до пользовательской документации.

ответ

6

Это очень открытый вопрос и зависит от многих факторов.

Вообще говоря, если вы используете язык с хорошими инструментами для создания документации (javadoc, doxygen, MS C# stuff), вы должны написать свою документацию над своими методами и заставить свои инструменты генерировать страницы. Преимущество заключается в том, что вы сохраняете источник вашего текста вместе с кодом, что означает, что он орнанизирован в логически правильном месте и легко редактируется, когда вы вносите изменения в поведение метода.

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

Примечание: здесь речь идет только о документации кода. Другие артефакты, очевидно, не могут храниться рядом с кодом - вики - отличное место для размещения этих документов. В качестве альтернативы, если вы используете некоторые CMS, вы можете просто скопировать их в какую-то папку в виде текстовых/pdf/любых файлов, которые можно редактировать через репозиторий. Преимущество заключается в том, что они остаются с репозиторием, если он перемещается, а wiki - нет (обязательно).

0

Моя компания использует различные Sharepoint и wiki. Sharepoint для конкретных документов, таких как требования, презентации, контракты и т. Д., В то время как вики используются в качестве справочного руководства для репозитория разработчика для учебных пособий по использованию внутренних библиотек.

1

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

Javadoc или DOxygen более подходит, если вы хотите получить доступную кодовую документацию.

Если вы имеете в виду пользовательскую документацию, вы можете взглянуть на DITA.

0

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

1

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

Однако, я искал использование ikiwiki для выполнения внутренних документов. Он интегрируется с вашей исходной системой подсчета (включая Git, Subversion, Mercurial, Bazaar, TLA и Monotone), поэтому все ваши документы отслеживают ваш проект. Он построен на Perl и имеет обширную систему плагинов (включая несколько языков разметки, причем по умолчанию используется Markdown). Кроме того, система управления версиями основана на плагинах, поэтому, если вы не используете сразу, вы можете добавить свои собственные. На вашем предпочтительном языке, если нужно, поскольку он поддерживает плагины, отличные от perl, тоже.

+0

Спасибо за ссылку ikiwiki, проверяя ее сейчас. Вы видели Trac Wiki? [link] (http://trac.edgewall.org/wiki/TracWiki) – ddri 2011-12-06 23:44:18

1

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

уценки/HTML/Javascript/файлов на основе относительно связанных документов для портативности (может работать на локальной файловой системе или вы можете бросить он на веб-сервере), встроенная обработка скриншотов (интерактивно изменяет размер) и с открытым исходным кодом на случай, если кто-то еще захочет что-то сделать с сумасшедшей штукой.

Источник документа написан на Markdown и передан в Html через Javascript во время выполнения браузера.

Mandown   -   http://wittman.org/mandown/

+0

Эй, отличный инструмент. Кстати, вы посмотрели на Xilize? Совсем аналогичная концепция, хотя и очень различная реализация. http://xilize.sourceforge.net/ – 2008-09-19 05:06:41

2

«Программное обеспечение документация» является очень общим термином. Существует «Документация конечного пользователя», «Документация разработчика», «Документация по QA». Первый из них обычно разрабатывается квалифицированными техническими специалистами. Другие могут быть динамически сформированы из вики, документации с исходного кода и т. Д. Весь этот процесс обслуживания обычно очень сложный, и каждая компания-разработчик работает по-своему. Но есть один необходимый момент для всех этих способов: каждый комендатор, архитектор, менеджер, qa engineer ДОЛЖЕН хранить хорошо организованную информацию, которая может быть полезной для других. И кто-то ДОЛЖЕН следить за этим хранением кусков и переставлять части, если это необходимо. Все эти шаги значительно улучшить все действия, связанные с процессом разработки.

3

Инструменты важны, но не слишком увязли в поиске волшебного инструмента. Никакой инструмент, который я нашел, не имеет «документально все, что волшебным образом использует крошечные невидимые эльфы». :-)

wiki будет работать нормально. Или Sharepoint. Или Google docs. Или вы можете использовать репозиторий SVN. Черт, вы могли бы сделать это с помощью ручек, блокнота и файловых шкафов, если вам действительно нужно. (Я действительно этого не рекомендую!)

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

В зависимости от вашей организации, области, типа продуктов, которые вы разрабатываете, и т. Д., Есть несколько решений для этого, но так или иначе вам нужно настроить систему, а использовать. Назначьте кого-то официальному царю документации, дайте им ключ и скажите им, чтобы они ударяли людей в голову каждый раз, когда они говорили «о да, я закончу документирование этой следующей недели ...». если это то, что нужно. :-)

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

Смежные вопросы