Рубрики
Разработка

Вы все еще пишете ТЗ в Word? — Тогда мы идем к Вам!

По долгу службы, с некоторых пор, пришлось заняться написанием ТЗ на разработку. Когда передо мной только встала такая задача, как оказалось, все делали это в MS Word. Я по началу тоже попробовал писать ТЗ в доке, но не выдержал и недели. Уж не знаю, или Word — это зло, или я просто не умею его готовить, но факт остается фактом, бОльшую часть времени я, в силу своей аккуратности и щепетильности, занимался форматированием: то отступы в списках разъедутся, то межстрочные интервалы в разных местах разные, а уж про разрешение конфликтов совместного редактирования — я вообще молчу! Да и ТЗ предназначались для разработчиков, которые любят простой текст, системы контроля версий и сидят на разных операционных системах. И я озадачился поиском более подходящих инструментов. И вот что у меня получилось.

Начальные требования

Нам нужен инструмент для написания технической документации. Инструмент должен поддерживать следующие возможности:

  • Нумерованные, не нумерованные вложенные списки.
  • Вставка изображений.
  • Простые таблицы.
  • Оглавление и переход по ссылкам.
  • Простая поддержка версионирования, желательно с использованием общеизвестных систем контроля версий.
  • Возможность комментирования и обсуждения.
  • Коллективная разработка.
  • Кросс-платформенность (MacOS/Linux/Windows).

Процесс

Возможности форматирования, необходимые нам, в полном объеме поддерживаются форматом Markdown. А в силу того, что md — это обычный текстовый файл, его можно хранить в любой системе контроля версий, как и исходный код. К тому времени у нас уже стояла связка gitlab + redmine для управления процессом разработки и код-ревью, о чем я уже писал ранее. Поэтому было решено изучать вопрос в этом направлении.

Самый сложный момент использования md и git заключался в том, что в написании ТЗ участвуют не только программисты, для кого markdown и git являются повседневными и естественными инструментами, но и люди, не имеющие прямого отношения к программированию. Для них, формат md может еще и не так страшен, но концепция систем контроля версий, что у разных людей один и тот же файл в один момент времени может находится в разных состояниях, выносит их мозг на раз.

Однако и этот барьер был преодолен. Я нашел редакторы markdown под Windows и MacOS, потому как самые далекие от программирования люди живут, в основном, на этих операционных системах. Так же нашел графические инструменты для работы с гит. Подготовил краткие и четкие инструкции по работе, перевел первый документ из .doc в .md, собрал совещание и провел вводный инструктаж.

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

В итоге, мы уложили разработку ТЗ в уже привычную нам схему:

  • Каждое ТЗ живет в отдельном репозитории git в системе gitlab.
  • У каждого ТЗ/репозитория есть мейнтейнер, то есть ответственный человек.
  • Стабильная версия ТЗ живет в ветке master.
  • Основная ветка разработки и написания ТЗ — dev.
  • Ветки master и dev являются защищенными, и только мейнтейнер может коммитить в них.
  • Любой человек, который хочет внести правки в ТЗ, делает отдельную ветку от актуальной ветки dev, вносит правки, и отправляет merge request через интерфейс gitlab ответственному за ТЗ.
  • Мейнтейнер одобряет merge request и исправления попадают в основную ветку разработки, откуда периодически выкатываются апдейты в публичный доступ, то есть ветку master.
  • Благодаря gitlab у нас есть удобный инструмент для код-ревью, где можно сразу увидеть вносимые изменения, прокомментировать и обсудить.
  • Для конечных потребителей ТЗ, то есть разработчиков и тестировщиков, gitlab вообще позволяет прямо в браузере иметь перед глазами актуальное ТЗ, не прибегая к каким-либо сторонним инструментам.

Используемые инструменты

Вот какие инструменты мы используем:

Редакторы markdown:

Git GUI:
Графических оболочек для работы с git, по большей части под Windows, не так уж и много, и почти все они страшные, но я советую SourceTree (http://www.sourcetreeapp.com). Это продукт компании Atlassian, недавно он стал бесплатным, и доступен для Mac и Windows.

Кстати, сейчас мы и пользовательскую документацию, такую как руководства пользователей, инструкции и прочее, переводим на markdown и git.

На этом, пожалуй, все. Надеюсь кому-то пригодится.

Похожие посты: