Перейти к содержимому

25.06.2014

6

Вы все еще пишете ТЗ в 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.

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

Узнайте больше из Web-Разработка
  • Павел

    markdown имеет довольно ограниченные возможности, большой развлетленный документ в нем не напишешь. Мы остановились на LaTeX – тоже текстовые файлы, но там реально можно сделать документ любой сложности. Возможность разбивать ТЗ на части и делать просто include в нужно место вообще неоценима. Единственный недостаток – порог входа больше чем в markdown (синтаксис посложней, компиляция не такая тривиальная).

    • Согласен. Воот именно поэтому мы выбрали md. Да, порой приходится жертвовать сложной разветвленой структурой, но у нас в написании документов участвуют разные люди (по большей части НЕ программисты) и md — очень просто и легок в освоении. Это сыграло свою роль.

  • Peter Beck

    Я всё ещё пишу всю документацию в word.
    И продолжаю писать. Office365 решает все проблемы.

  • Timur

    Эх, хрустальная мечта — правильный документооборот, семантически структурированные документы… Увы, социальную проблему техническими средствами не решить — далеко не все готовы к такому, даже стили и пр. семантическое форматирование в Word мало кто умеет. Про MD, LaTeX и DocBook я даже не говорю. Похоже, значительная часть людей в принципе не способна так воспринимать. Уж лет 12 наблюдаю это. По-моему, максимум возможного — внутри группы решить (компания, отдел, команда), но это некоторая изоляция, что противоречит изначальной цели — эффективное взаимодействие.

    Практический вопрос. А как на счёт внешних участников разработки ТЗ типа конечных заказчиков? Они получают ТЗ в готовом виде (каком? pdf?) без возможности редактирования и дают обратную связь только через менеджеров, владеющих технологией разработки ТЗ? Или это сугубо внутренняя штука?

    Трудно представить себе вариант, где заказчику усложняют жизнь настолько, что ему приходится осваивать специальные инструменты (причём на английском) только чтобы быть заказчиком 🙂

    • Да, согласен. Мечта…. Именно поэтому надо начинать с малого, хотя бы локально, в рамках команды, отдела, компании внедрять такие штуки.

      С точки зрения внешних потребителей документации, конкретно у нас ситуация следующая: это все внутрення проектная документация, так что проблем нет. Однако в случае необходимости обсуждения ТЗ с внешними пользователями, мы просто экспортируем его в pdf. То же самое происходит и с пользовательской документацией (руководства, записки и пр), мы экспортируем её в pdf и поставляем их.

  • Елена

    Тексты в разметке Markdown можно писать даже в Word, абсолютно не зная разметку вообще, если поставить плагин Writage (www.writage.com).