Столкнулся с необходимостью выбрать инструментарий для ведения документации по проекту. Получается, что если в команде нет отдельного (специально выделенного) человека, который ведёт всю документацию, то инструментарий должен поддерживать коллективную разработку документации. Как минимум — уметь делать versioning, diff и rollback.

Два ключевых слова — “документация” и “коллективная” приводят к очевидному решению — wiki. Решение настолько очевидно, что можно найти testimonials людей, использовавших wiki для документирования разработки software:

Во-первых, в разработке док участвовали все: манагеры, девы, кюэйцы. Каждый со своей позиции (решая профильные вопросы) и в целом.
Во-вторых, оценивать изменения состояния проекта было легко. У нас была круглосуточная разработка (головной офис в штатах) и поэтому за время сна могло многое измениться.
В-третьих, самые болезненные места было сразу видно и можно было прямо с утра озадачиться раздачей пинков в нужных направлениях. Или тут же решить самые острые вопросы (поменяв заодно тег вопроса на тег ответа). Или поставить новые проблемы в ответ на.
В-четвертых, документация была всегда у всех под рукой. Гибкая. Актуальная.
В-пятых, она активно росла. Было негласное правило: хочешь задать вопрос по теме, которая еще не описана? Впиши все, что ты помнишь, в той мере, какой считаешь нужным.
В-шестых структуру самого дерева мы регулярно реструктурировали, что позволяло нам при проектировании новых кусков логики опираться на схему уже существующих.

Очевидно, что сама по себе wiki не справляется с задачей: нужны костыли для привязки к багтрекеру, svn-у, php-docу (или его аналогу). Ещё более очевидно, нужен “архивариус” — человек, который будет поддерживать порядок в документации, реструктуризировать дерево. Похоже, что при определённой активности и дисциплинированности пользователей (т.е. разработчиков, тестеров и менеджеров) роль архивариуса удастся свести именно к поддержанию порядка.

При этом меня не покидает ощущение того, что wiki-разметка — это недо-html. А в компании, занимающейся web-разработками, основы html знает даже корпоративная морская свинка™. Спрашивается: зачем людям, знающим html, насиловать себя и писать вместо <i>привычных тегов</i> //какие-то недотеги//, которыми они нигде, кроме этой самой wiki не пользуются, в отличие от нативных html тегов?

Среди всех претензий к wiki её недо-htmlьность — самая мелкая.

А теперь самое время вернуться к тому, с чего всё это начиналось: нам нужен инструмент, позволяющий вести коллективную разработку документации. Как минимум — уметь делать versioning, diff и rollback.

А ведь у нас уже есть такой инструмент: это Control Version System, система контроля версий. Стандартная CVS позволяет делать versioning, diff и rollback для текстовых файлов.

Итак, самое дешёвое решение — вести документацию в текстовых файлах, контроль версий возложит на CVS, которая уже есть в проекте. Грубо говоря, если в CVS есть директория Source с исходниками проекта, то рядом надо сделать папку Docs с его документацией в текстовых файлах.

Беда в том, что документация — это не текст. Даже если обойтись без таблиц, иллюстраций и форматирования, документация — это как минимум гипертекст. Значит, надо вести документацию в формате html, и хранить её в CVS, ибо html файл — это текстовый файл. Редактировать документацию сможет каждый, как и в случае с wiki — для этого подойдёт любой html-редактор, даже блокнот.

Versioning для html файлов будет по-прежнему обеспечивать CVS. Единственное, что надо согласовать — это правила форматирования документации в html. Типа: для жирного используем <b>, а не <strong>; абзацы делаем с помощью <p>; ссылки ставим только относительные. Точно такие же соглашения существуют и в отношении кода: как ставим {скобки}, что используем для табуляции — пробелы или табы.

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

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

Если вы используете SVN под Windows, то почти наверняка это — Tortoise SVN.

В стандартную установку Tortoise SVN входит не только SVN клиент, с помощью которого можно делать Checkout, Update и Commit, но и SVN сервер.

Соответственно, если у вас стоит Tortoise SVN, то вы можете поднять свой локальный SVN сервер.

Зачем это необходимо? SVN — это удобно, и это реально сохраняет время. Максимум, на что хватает среднего девелопера при интенсивной разработке без системы контроля версий — сделать текущий бекап проекта, скопировав все текущие файлы в папку вида project_name.20080709.backup. Единственное, что позволяет такая система сделать удобно и быстро — откат к выбранной “версии” проекта. Никакого show differences, restore to revision и прочих прелестей.

В общем, если вы профессионально занимаетесь написанием программ и не пользуетесь никакой системой контроля версий, вы лишаете себя многих прелестей.

Итак, первым делом надо создать репозиторий. Для него подойдёт любая пустая директория, например c:\Repository\. В контекстном меню этой директории выбираем команду TortoiseSVN » Create Repository here. Файловая система FSFS подойдёт.

Пусть мы хотим добавить в репозиторий директорию d:\projects\megashit\source\. В контекстной меню папки c:\Repository\ вызываем TortoiseSVN » Repo-browser. Внутри Repo-browser у нас должна быть видна директория file:///C:/Repository/, в её контекстном меню выбираем add folder и добавляем директорию d:\projects\megashit\source\, которую затем переименовываем в megashit с помощью пункта контекстного меню rename.

Теперь делаем бекап директории d:\projects\megashit\source\ и удаляем из неё все файлы (они уже есть в репозитории). В контекстном меню делаем Checkout из file:///C:/Repository/megashit/.

Если Checkout отработал нормально, то в папке d:\projects\megashit\source\ окажутся те же файлы, что были в ней до удаления + скрытая папка .svn, которую не надо трогать.

Теперь в контекстном меню папки d:\projects\megashit\source\ должны появиться команды SVN Update и SVN Commit, с помощью которых можно работать с репозиторием (svn-адрес которого, напомню, file:///C:/Repository/megashit/).

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

Программа Programeter на основе анализа исходников проекта в репозитории позволяет оценить/измерить такие характеристики работы каждого программиста:

• уровень знакомства программиста со всей базой исходников;
• количество нового, привнесённого этим программистом кода в репозиторий;
• уровень “выживаемости” кода программиста;
• размер общего вклада программиста в репозиторий;
• уровень активности в течение одного месяца;
• ориентированность на сотрудничество с другими программистами;
• среднюю сложность написанного кода;
• соотношение объёма написанных комментариев к объёму написанного кода.

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

Почему менеджмент, принимающий решения на основе таких показателей маразматичен?

Потому что все эти циферки накручиваются, с разной степенью лёгкости.

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

Сложность кода накручивается тоже очень легко; искусственное завышение размера общего вклада также не вызывает особых проблем у опытного программиста.

А накручивать обязательно будут, если накрутка приносит какую-то выгоду (повышение или непонижение з/п, например). Вот выдержки из реальной истории о том, как в одной конторе начали оценивать работу программистов по количеству коммитов в неделю (в переводе Сергея Можайского):

“С помощью его скрипта он мог сделать из одного коммита 20-30. Он вполне мог ожидать повышения, поскольку его продуктивность [по меркам системы] возросла более чем на 600%.

Несмотря на то что это длится уже два месяца, удивительно, что начальник и не подозревает о том, что большинство коммитов - однострочные изменения, или что исправление опечатки в слове “guarantee” в форме заказа потребовало более дюжины коммитов.”

Хорошо, если накрутчики будут просто не ухудшать код своими накрутками, а если начнут ухудшать? Выгребать и фиксить будет вся команда, а не только накручивающие.

В общем, если в вашем проекте решения о уровне полезности программистов принимаются не на основе мнения ведущего программиста, а на основе таких вот “показателей надоев”, то дело плохо.

Есть задача: внедрить в контору систему контроля версий. В конторе есть FreeBSD сервер и машины разработчиков under WinXP. В конторе разрабатываются два типа проектов: общие и личные.

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

Насколько я понимаю, на сервере нужен SVN сервер, а на машинах разработчиков какой-нибудь SVN клиент, который может работать с удалённым сервером и представлять из себя локальный сервер тоже. Или не обязательно SVN?

Если меня читает кто-нибудь, имеющий релевантный опыт: помогите разобраться с предметной областью, пожалуйста. Как называется то, что мне надо, и какой софт лучше всего ставить. Спасибо.