Документация

Ищем как вести документацию

Идея:

Документация - это, естественно, очень важная часть работы. Как и где её правильно вести? Несмотря на долгий опыт работы над различными проектами могу сказать, что - Не знаю! Много было всего, но ничего не устраивало. Соответственно - "будем искать".

Цель 1:

Начиная поиск по системе документирования необходимо задаться вопросами по использованию этой документации. Правильно поставленные вопросы это путь к правильным ответам.
Первое - Что же я хочу от документации? Что мне не нравилось раньше? И Чего мне не хватало?

• Много тратить времени на документацию - нет ни желания, ни возможности.
• Она должна быть лаконичной, но в тоже время должна максимально отображать суть того, что в ней задокументировано.
• Доступность и не захламлённость. Поиск по документации должен быть быстрый и лёгкий. Ответы на вопросы должны находиться быстро.
• История документации. Всегда мне не хватало нормальной возможности анализа жизни документации. Кем, зачем, когда и почему было написано то или иное требование или решение?
• Память. Никакая идея на будущее или продуманная работа, которую можно будет реализовать только после нескольких других итераций работ или фич, не должны упасть в общую кучу и потеряться там навечно или пока не будет поздно.
• Документация должна быть живая. Актуальность документации очень важна. Ситуации, когда что-то разрабатывается или придумывается на основании неактуальной информации, не должно быть, даже на уровне возможности.
• И снова к жизни документации. Жизнь - это движение. Жизнь - это способность изменяться и адаптироваться.

План:

• Просмотреть и проанализировать текущий рынок систем.
• Выбрать из них подходящий мне.
• Настроить его под себя.
• Начать использование, написав Дизайн Документ по первому проекту.

Реализация 1:

Естественно, в начале я начал поиск по уже известным мне системам:

• Confluence
• Google Docs
• One Note

Ничего не выходило. Чувство, что я снова пытаюсь увязнуть все в том же болоте и наступаю на те же грабли, совершая все те же ошибки, не покидало меня все это время.
Я решил подойти к этому вопросу с другой стороны и начал просматривать другие площадки для хранения документации. Все их перечислять не буду, перелазил весь интернет, и все это были просто аналоги. Даже подумывал в сторону развернуть у себя что-нибудь типа WordPress или MediaWiKi. Но все это были те же яйца, только вид с боку.
Спринт я откровенно "просрал". А планировал - найду систему, настрою по-быстрому, создам шаблончики и структуру, и в путь. Не так то все и было.
А что все это значит? Если двери в этом коридоре так или иначе ведут к одному и тому же, не нужному мне месту, то коридор выбран не правильно. Возвращаемся назад и начинаем переосмысление.

Цель 2:

Предыдущие цели по своей сути остаются такими же, но теперь это не цели, а просто Вижен, Идея. Они, как показала практика, слишком абстрактны и не раскрывают всей глубины вопроса. А значит вопрос поставлен не верно!
И цель поменялась:
Найти правильные вопросы! (ответ должен быть 42)

Реализация 2:

Прежде чем задаваться вопросами по этой теме, надо для себя решить

Что такое документация?

В первую очередь документация - это такой же продукт как и все остальное. А соответственно:

• У неё есть потребитель.
• Она решает какие-то проблемы потребителя.
• Как продукт, она доставляется потребителю в каком-то виде.
• И немаловажно - у неё есть цена, и она должна быть не больше, чем стоимость решённых проблем. (Выгодная цена).
• "Необходимое и достаточное" - это тоже больше вопрос цены. Оптимальный объем - это важно с точки зрения затраченных ресурсов. Но и недостаточность информации не должна сказываться на качестве продукта.

Для кого и для чего документация?

Понятное дело, что в моем случае она нужна для меня одного. Но, так как у меня размножение личности :) , то рассмотрим просто разные ипостаси.

Гейм Дизайнер.
1. Техзадания на разработку фичи - для того, чтобы знать, что необходимо продумать\добавить\заполнить.
2. Заметки и продумывание концепций функционала.
3. Документация реализованного функционала - для того, чтобы было от чего отталкиваться при продумывании новых фич.
4. Памятка. Идеи и продуманный функционал, который был отложен, или имеет блокирующие его нереализованные функции - для того, чтобы можно было вернуться к этому решению, вспомнить все нюансы и не продумывать его заново, либо сразу же отказаться из-за нецелесообразности, тем самым экономить время.

Art.
1. Техзадание на отрисовку\моделирование\анимацию - для понимания, что от него требуют.
2. Набор технических требований к Арту, чтобы при разработке не выходить за рамки доступного.
3. StyleSheets и референсы - для того, чтобы поддерживать общий стиль в продукте.

UI и UX. Плюсом к тому, что нужно для Art'а.
4. Схемы и описание реализованного функционала - для оптимального использования готового продукта, а также для учета при разработке уже написанных систем.

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

QA.
1. Критерии приемки функционала - для проверки работоспособности и удовлетворения требований выполненных задач.
2. ЮзКейсы и ТестКейсы - для различных этапов тестирования.

Маркетинг.
1. Документация реализованного функционала - для понимания, что они продают.
2. Внутренний документооборот - для хранения табличных данных, статистик, рефералов и тд. (этот вопрос еще предстоит лучше изучить на более поздней стадии разработки).

Поддержка пользователей.
1. Список версий и вводимого в них функционала - для предоставления справочной информации пользователям, а также для оперативного реагирования на уже исправленные проблемы пользователя и для информирования пользователей о закрытии их боли.
2. Списки болей пользователей - для структурирования их, анализа и присвоения им приоритетов.

Аналитика.
1. Документация реализованного функционала с точки зрения аналитических данных - для построения различных воронок и выборок.

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

Как-то это все очень похоже на user story в Agile:
"Я, Гейм Дизайнер, хочу документацию реализованного функционала - для того, чтобы было от чего отталкиваться при продумывании новых фич." :)

В каком виде нужна эта документация?

Теперь можно разобрать все эти запросы на документацию по цене, объему, и как её можно предоставить.

Техзадание.
Оно необходимо только на этап разработки, так, чтобы исполнитель знал, что ему делать и как ему это делать. По завершении этого задания и приемки его, оно уже не нужно. Разве что для истории, чтобы можно было всегда узнать, ради чего то или иное было сделано.
Само собой напрашивается, что это просто таски и в них должно быть по максимуму отраженно техническое задание достаточное для его реализации.
Для хранения истории конечно можно так и оставить, и если кому-то надо, пусть перелопачивает кучу старых завершённых тасков в поисках нужной информации. Но можем ли мы это безболезненно с минимальными затратами упростить. Для некоторых вещей определенно можем, для других - надо подумать.
На примере заданий для программистов. Я всегда пропагандировал и даже требовал соблюдения нескольких несложных правил на этот счет:
1. Ничто, ни единой строчки кода не должно быть залито в репозиторий без соответствующего таска.
2. В комментарии к коммиту в репозиторий должен быть прописан номер таска на основании которого он сделан.
Для чего это делается? В любой момент времени можно узнать для чего была написана та или иная строчка кода.

Связка СистемыКонтроляВерсий с ТаскМенеджером

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

Критерии приемки.
Так как я использую таски для техзадания, то критерии приемки для QA ложатся сюда и вносятся вместе с ним.

Техническая документация проекта.
Раз уж речь пошла о программистах, то сразу разберем и этот их тип документации.
Так как она от программистов и для программистов, то и должна быть там, где работают программисты: в коде.
Написание комментариев в коде, обязательное summary, это все должно быть. А если в комментарии еще добавлять номера тасков, так это вообще будет прелесть (надо попробовать, потом сделать выводы). В дальнейшем можно собрать автосборку всего этого добра в словарь и пользоваться им вне кода.
А вот для блок-схем можно конечно использовать drow.io, и они будут полезны как программистам, так и UX и возможно QA. Но как часто и как сильно это нужно? Вполне вероятно, что для меня будет достаточно и документации описанной выше.

ГД документация.
Тут уже немного сложнее и в тоже время проще.
То, что выходные данные их работы - это таски user story, мы уже понимаем из того, что разобрали выше, а соответственно делать какие то Дизайн-документы для исполнителя - это излишняя, дублирующаяся работа. "Необходимое и достаточное" тут работает на полном ходу.

Заметки\Идеи\Памятки.
Я думаю, что для этого мне хватит этого Блога. Да, я рискую излишним раскрытием информации о своем продукте, но... да пусть будет так, это будет интересно.

Документация реализованного функционала. Технические требования и подобная документация. ЮзКейсы и ТестКейсы.
Помимо блога надо бы складировать такую инфу куда-то. Она нужна как ГД, так и Поддержке и Маркетингу. И тут есть идея. Не знаю, как она у меня приживется, но её надо опробовать, притереть и допилить напильником.
Хочу максимально использовать тут версионность (git). Этому я посвящу отдельную запись, так как эта уже и так разрослась :)
Но в этой документации надо придерживаться принципа "Необходимое и достаточное", вся она должна быть изложена кратко и понятно любому обывателю, а более сложная техническая информация и требования у нас переходят к таскам.

Документация для Маркетинга, Аналитики и Поддержки.
Об этом еще рано что-то говорить, она будет необходима на более поздних этапах. И можно будет это делать на основе выживших идей по документации на этапах разработки.

Итого:

Не просто было найти решение для этой задачи. И все это будет интересный эксперимент. Я уверен, что все это еще будет меняться и улучшаться. На то оно и жизнь, а Жизнь - это движение, Жизнь - это способность изменяться и адаптироваться.