Всем известно, что хорошо документированная разработка программного обеспечения ведет к успеху. Однако обычно это означает, что в документ будет вовлечен не только простой текст, но и двоичное содержимое, например диаграмма UML. И я слышал, что многие так говорят. Система контроля версий не подходит для двоичных файлов. Я полностью понимаю и согласен с этим вопросом. Я спросил нескольких опытных разработчиков, где должно быть лучшее место для хранения документов, и я получил ответ «вики». Вики это хорошо, но я рассмотрел еще одну потенциальную проблему. Как исходный код, который был сохранен в системе управления версиями, может соединиться с соответствующим документом в вики? Допустим, кто-то клонирует хранилище git или mercurial. Как он может легко найти документ? Или я что то пропустил?
Я знаю, что некоторые вики-системы могут интегрироваться с системами контроля версий. Но я беспокоюсь не о возможности интеграции. Если вы клонировали исходный код из репозитория git и через некоторое время вы садитесь в поезд и хотите продолжить работу в поезде в автономном режиме (что является большой особенностью DVCS). Затем вы внезапно понимаете, что у вас нет доступа к документу, поскольку вы работаете в поезде в автономном режиме. С другой стороны, если бы документ хранился в репозитории git, у вас был бы доступ к документу с клонированным репозиторием.
источник
Ответы:
Вместо того, чтобы писать документы, PDF-файлы и другие виды файлов, почему бы вам не раскрыть весь потенциал WIKI в качестве инструмента для совместной работы? Вы можете написать свои документы там, прикрепить свои диаграммы и даже лучше: если вы используете Fitnesse , вы можете превратить свои вики-страницы в действительно полезную и живую документацию, поскольку они могут стать исполняемой спецификацией.
Остерегайтесь этого. Документы не приведут к успеху, так как они не превратят дерьмовый код в хороший. Но документы - это часть пути к успешному программному обеспечению. Но только часть, и они не заменят хороших практик и хороших людей.
источник
Поскольку множественные ответы указывают на Trac как на предложение, я бы хотел предложить аналогичную, но, на мой взгляд, лучшую альтернативу: Redmine .
Redmine - это решение для управления проектами, включающее Wiki, репозиторий документов и интеграцию управления версиями. По моему опыту, он также написан на Ruby on Rails, и его легче расширять и взламывать, чем Trac.
Более того, им действительно легко пользоваться, и его легко получить командой.
Функции:
Для ваших автономных потребностей мне не нравится идея загромождать контроль версий проектной документацией. Я уверен, что у вас есть причины спросить об этом, но на самом деле как часто вы не в сети и вам нужен доступ к проектной документации? Скорее всего, это действительно угловой случай.
источник
Как вы упомянули, некоторые вики (например, Ikiwiki ) имеют возможность хранить свои данные в Git. Учитывая это, вы можете связать документацию как подмодуль Git в своем обычном исходном репозитории.
При вышеописанной настройке извлечение исходного кода и обновление подмодулей приведет к получению последней копии документации. Оффлайн, вы можете редактировать каждый по своему желанию. Когда вы вернетесь в сеть, оба могут быть перенесены обратно в любое место общего доступа, которое вы используете.
Неудобной частью этого является то, что всякий раз, когда документация обновляется (даже через веб-интерфейс Ikiwiki), вам также необходимо будет обновить соответствующий подмодуль в исходном репозитории Git. Тем не менее, это может быть легко автоматизировано.
источник
Имеет смысл хранить документацию в том же хранилище, что и исходный код. Сфинкс кажется мне хорошим вариантом.
источник
Trac предоставляет интерфейс к Subversion, интегрированную Wiki и удобные средства отчетности. http://trac.edgewall.org/
Но я не знаю о вашем установленном стеке.
источник
Я бы не стал подчиняться офлайн-работе. Я бы использовал ресурс, с которым проще всего работать всем. Например, если вы пишете код PHP, я бы предложил использовать встроенную документацию, которая может быть сгенерирована PHPDocumentor . Он может быть сгенерирован где угодно, и есть плагин для Trac . Затем онлайн или выключен, у вас есть доступ к документации, тоже довольно быстро.
Ключ о юзабилити. Если его трудно поддерживать, он начнет страдать. Когда это начинает страдать, качество документации падает. Когда это происходит, люди начинают жаловаться, и тогда все идет под гору.
источник
Использование вики для хранения документации имеет для меня большой смысл.
Veracity - это пример DVCS, который позволяет более тесно интегрировать вики-контент и исходный код.
источник