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

Всем известно, что хорошо документированная разработка программного обеспечения ведет к успеху. Однако обычно это означает, что в документ будет вовлечен не только простой текст, но и двоичное содержимое, например диаграмма UML. И я слышал, что многие так говорят. Система контроля версий не подходит для двоичных файлов. Я полностью понимаю и согласен с этим вопросом. Я спросил нескольких опытных разработчиков, где должно быть лучшее место для хранения документов, и я получил ответ «вики». Вики это хорошо, но я рассмотрел еще одну потенциальную проблему. Как исходный код, который был сохранен в системе управления версиями, может соединиться с соответствующим документом в вики? Допустим, кто-то клонирует хранилище git или mercurial. Как он может легко найти документ? Или я что то пропустил?

Я знаю, что некоторые вики-системы могут интегрироваться с системами контроля версий. Но я беспокоюсь не о возможности интеграции. Если вы клонировали исходный код из репозитория git и через некоторое время вы садитесь в поезд и хотите продолжить работу в поезде в автономном режиме (что является большой особенностью DVCS). Затем вы внезапно понимаете, что у вас нет доступа к документу, поскольку вы работаете в поезде в автономном режиме. С другой стороны, если бы документ хранился в репозитории git, у вас был бы доступ к документу с клонированным репозиторием.

Действительно ли WIKI подходит для хранения документов для разработки программного обеспечения?

Вместо того, чтобы писать документы, PDF-файлы и другие виды файлов, почему бы вам не раскрыть весь потенциал WIKI в качестве инструмента для совместной работы? Вы можете написать свои документы там, прикрепить свои диаграммы и даже лучше: если вы используете Fitnesse , вы можете превратить свои вики-страницы в действительно полезную и живую документацию, поскольку они могут стать исполняемой спецификацией.

Всем известно, что хорошо документированная разработка программного обеспечения ведет к успеху

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

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

Redmine - это решение для управления проектами, включающее Wiki, репозиторий документов и интеграцию управления версиями. По моему опыту, он также написан на Ruby on Rails, и его легче расширять и взламывать, чем Trac.

Более того, им действительно легко пользоваться, и его легко получить командой.

Функции:

• Поддержка нескольких проектов
• Гибкое управление доступом на основе ролей
• Гибкая система отслеживания проблем
• Диаграмма Ганта и календарь
• Управление новостями, документами и файлами
• Ленты и уведомления по электронной почте
• За проект вики
• По проектам форумов
• Время отслеживания
• Пользовательские поля для вопросов, записей времени, проектов и пользователей
• Интеграция SCM (SVN, CVS, Git, Mercurial, Bazaar и Darcs)
• Создание проблемы по электронной почте
• Поддержка множественной аутентификации LDAP
• Поддержка самостоятельной регистрации пользователей
• Мультиязычная поддержка
• Поддержка нескольких баз данных

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

Как вы упомянули, некоторые вики (например, Ikiwiki ) имеют возможность хранить свои данные в Git. Учитывая это, вы можете связать документацию как подмодуль Git в своем обычном исходном репозитории.

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

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

Имеет смысл хранить документацию в том же хранилище, что и исходный код. Сфинкс кажется мне хорошим вариантом.

• он принимает файлы reStructuredText в качестве входных данных, которые легко редактировать и различать
• генерирует гиперссылки (HTML, PDF, ...)
• Вы можете ссылаться на свой исходный код (Python, C, C ++, JavaScript)

Trac предоставляет интерфейс к Subversion, интегрированную Wiki и удобные средства отчетности. http://trac.edgewall.org/
Но я не знаю о вашем установленном стеке.

Я бы не стал подчиняться офлайн-работе. Я бы использовал ресурс, с которым проще всего работать всем. Например, если вы пишете код PHP, я бы предложил использовать встроенную документацию, которая может быть сгенерирована PHPDocumentor . Он может быть сгенерирован где угодно, и есть плагин для Trac . Затем онлайн или выключен, у вас есть доступ к документации, тоже довольно быстро.

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

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

Veracity - это пример DVCS, который позволяет более тесно интегрировать вики-контент и исходный код.