«Простой» способ документирования проекта

Поделитесь опытом документирования своих проектов. все чаще сталкиваюсь с проблемой «забыл, что уже сделано». В современном программировании когда одна апликация может включать в себя разные клиенты, а тем более микросервисы на бекенде и разные интегрированые сервисы, часто при переключении, к примеру, на разработку фронта на 2-3 недельки в последствии забываешь, не то что как, а что реализовано на бекенде... Есть какой-то «old school» метод документирования?

LinkedIn
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Допустимые теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Олдскул предполагал сперва документы написать/проверить/пока не будет готово, затем по ним строго (и, конечно, скучно) и внимательно делать, пока не заработает, а там уже приёмочные тесты лежат готовые и проверяют ровно то, что было когда-то предусмотрено.

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

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

Есть олдскул-подход, который и сегодня доступен — вести страницу-бложик в Confluence по каждому epic в стиле:

== 16 июня
Хочу сделать то и это, чтобы было так и так.
Понадобится то и это. Не забыть то и сё.

== 17 июня
Забыли про то и сё, хорошо, что было записано.
Ок, надо ещё такую задачу решить, бо без неё будут такие-то последствия.

Это пишется БЫСТРО перед тем, как браться за имплементацию, это человекопонятный текст, это митинг-ноутс, это высокоуровневая документация и одновременно летописец и, вероятно, отчёт. Ключевой момент в подаче: это объявление для «завтрашнего себя» о том, что надо сделать, и зачем, и почему именно так.

Сюда же можно подвязать ссылку на детализацию задач — типа классическая документация.

В целом это такая же документация, как и все, с неизбежными фэйлами вроде «1 декабря, давно ничего тут не писал, ну да ладно» и «А это не будем писать, бо всуе нельзя упоминать».

Есть какой-то «old school» метод документирования?

Самое первое что нужно сделать так это фиксировать ТЗ. Что до кода, есть, 1) называется самодокументирующийся код без «приколов» (ну или с, но тогда с их документацией либо в коде либо в другом месте). Особо помогают документированию именованые типы на каждый чих вместо хешмап из примитивов, и доменные ошибки на все возможные исходы событий, но далеко не во всех ЯП такое возможно. 2) Пилить всё микрофичами, на каждую микрофичу пилить таску в трело/другой тулзе и описывать что было сделано прикреплять ссылку на коммит, а в каждом коммите делать ссылку на таску.

Есть какой-то «old school» метод документирования?

Во времена ватерфола была одна вещица между постановкой задачи и её заливкой в дев.
Называлась «Дизайн документ», где девелопер сначала описывал планируемый дизайн,
потом этот ДД аппрувили, указывая на ошибки, грабли итп,
после чего девелопер делал эстимейт и приступал к имплементации.
После код ревью девелопер вносил в ДД днные о внеплановых изменениях, которые он не предвидел.
Во времена потогонного скрама про «ДД» конечно не вспоминают — дешевле же ошибиться в разы с эстимейтом, а потом переделать.

Есть какой-то «old school» метод документирования?

Липкие листочки на мебель. Охрененно помогают в имитации бурной деятельности

Есть какой-то «old school» метод документирования?
  1. Vision Document
  2. Design Document
  3. README в каждом репозитории

miro.com

Используем на моих проектах. Широкий функционал, коллаборация.

Есть. Ху*ришь всё в один текстовый файл сырым логом комментов, потом по нему отлично работает поиск. Выгода в том, что ты держишь этот файл постоянно открытым.

Отдельная часть этого файла, а может и отдельный файл — это TODO лист. Очень знаешь ли помогает, особенно если проект сложный, тысячи мелких нюансов. Потом этот файл просто перечитываешь как чеклист, и никакого беклога тебе не нужно.

Расшара этого файла — и для команды в 2-3 человека уже хватает. Дёшево, сердито, быстро. И бэкап редактору настроить на всяк случай не помешает.

PS. Начинай с фронта, так проще. На бэкенде тупо покорми «затычками» (стабами, моками, etc.), возвращающими одно и то же, а уже потом реализовывай. Сэкономишь туеву хучу времени на его переписывание. И главное, если чё не так — можно быстро подправить пока пишешь фронт. И даже протестить после, не написав бэкенда, и даже показать заказчику.
И маленький совет: не удаляй эти затычки когда код пойдёт в продакшен. Лучше взведи флаг, позволяющий на них переключиться, и используй его для тестов, в том числе удалённо. Поможет быстро выяснить на какой стороне бага, на фронте, на бэке, или на звеньях между.

Благодарю, мне такое как раз пока подойдет.

по стадиям:
1. гугл дока одна общая файлень (правят те кому можно)
(1.1. когда таблицы становятся слишком большими/значимыми — докидываешь гугл таблицу, например для проектной схемы БД «по бедному по простому (удобно для полей-которые-наверное-нужно-еще)
2. +схемка «всей вселенной» (когда уже одного текста мало), 1 файлик
3. проектная Вики на бесплатном движке (становится нужной когда «люди приходят и уходят»)
Это проверено — это работает.

По супербедному/быстрому (зато всегда под рукой) можно исхитриться запинать все это дело в Evernote.

Гуглодока тормозная и глючащая. В какой-то момент может оказаться что вы видите разные версии. А уж баги на сохранении...

хз я лично не сталкивался. знаю есть баги если таблицу к примеру с мобильного обновляют одни, а с десктопов — другие
зато out-off-the-box и можно втыкать на смартфоне даже у бусіку додому до жмеринки. и версионность еще, что бывает спасает.

все чаще сталкиваюсь с проблемой «забыл, что уже сделано».

Можно на каждое «сделано» заводить небольшую трелло карточку с названием, описанием и ссылкой на изменения в коде, например.

Wiki файлы в репозитории? Диаграммы? Google Docs. Витамины для памяти попить.

Это не для памяти ))

Есть какой-то «old school» метод документирования?

Отдел документации на зарплате, который выпускает печатный мануал на тыщи страниц

это на предприятиях, а простому «джедаю» как быть ?

Либо документацию надо писать, либо код — лучшая документация. Других вариантов нет

вчера наткнулся на интересную статью о том какие требования к формату сообщений для коммитов на Angular OpenSource, взял на вооружение, это должно решить 80% моих «проблем»

Подписаться на комментарии