«Простой» способ документирования проекта
Поделитесь опытом документирования своих проектов. все чаще сталкиваюсь с проблемой «забыл, что уже сделано». В современном программировании когда одна апликация может включать в себя разные клиенты, а тем более микросервисы на бекенде и разные интегрированые сервисы, часто при переключении, к примеру, на разработку фронта на
22 коментарі
Додати коментар Підписатись на коментаріВідписатись від коментарівОлдскул по-современному: habr.com/...mpany/lamoda/blog/485926
Олдскул предполагал сперва документы написать/проверить/пока не будет готово, затем по ним строго (и, конечно, скучно) и внимательно делать, пока не заработает, а там уже приёмочные тесты лежат готовые и проверяют ровно то, что было когда-то предусмотрено.
Если надо внести изменения в проект — сперва внести изменения в документацию, применить тайные и явные техники проверки требований на цельность и нерушимость, получить аппрув на внесение изменений, затем строго и внимательно делать, пока не заработает... Не самая здоровая атмосфера старых добрых пятидесятых годов, на самом деле.
В современной разработке нечто подобное бывает, если клиент сложный, и с ним уже хочется судиться.
Есть олдскул-подход, который и сегодня доступен — вести страницу-бложик в Confluence по каждому epic в стиле:
== 16 июня
Хочу сделать то и это, чтобы было так и так.
Понадобится то и это. Не забыть то и сё.
== 17 июня
Забыли про то и сё, хорошо, что было записано.
Ок, надо ещё такую задачу решить, бо без неё будут такие-то последствия.
Это пишется БЫСТРО перед тем, как браться за имплементацию, это человекопонятный текст, это митинг-ноутс, это высокоуровневая документация и одновременно летописец и, вероятно, отчёт. Ключевой момент в подаче: это объявление для «завтрашнего себя» о том, что надо сделать, и зачем, и почему именно так.
Сюда же можно подвязать ссылку на детализацию задач — типа классическая документация.
В целом это такая же документация, как и все, с неизбежными фэйлами вроде «1 декабря, давно ничего тут не писал, ну да ладно» и «А это не будем писать, бо всуе нельзя упоминать».
Самое первое что нужно сделать так это фиксировать ТЗ. Что до кода, есть, 1) называется самодокументирующийся код без «приколов» (ну или с, но тогда с их документацией либо в коде либо в другом месте). Особо помогают документированию именованые типы на каждый чих вместо хешмап из примитивов, и доменные ошибки на все возможные исходы событий, но далеко не во всех ЯП такое возможно. 2) Пилить всё микрофичами, на каждую микрофичу пилить таску в трело/другой тулзе и описывать что было сделано прикреплять ссылку на коммит, а в каждом коммите делать ссылку на таску.
Во времена ватерфола была одна вещица между постановкой задачи и её заливкой в дев.
Называлась «Дизайн документ», где девелопер сначала описывал планируемый дизайн,
потом этот ДД аппрувили, указывая на ошибки, грабли итп,
после чего девелопер делал эстимейт и приступал к имплементации.
После код ревью девелопер вносил в ДД днные о внеплановых изменениях, которые он не предвидел.
Во времена потогонного скрама про «ДД» конечно не вспоминают — дешевле же ошибиться в разы с эстимейтом, а потом переделать.
Липкие листочки на мебель. Охрененно помогают в имитации бурной деятельности
git log --oneline -n37 --grep '^Merge'miro.com
Используем на моих проектах. Широкий функционал, коллаборация.
Есть. Ху*ришь всё в один текстовый файл сырым логом комментов, потом по нему отлично работает поиск. Выгода в том, что ты держишь этот файл постоянно открытым.
Отдельная часть этого файла, а может и отдельный файл — это TODO лист. Очень знаешь ли помогает, особенно если проект сложный, тысячи мелких нюансов. Потом этот файл просто перечитываешь как чеклист, и никакого беклога тебе не нужно.
Расшара этого файла — и для команды в2-3 человека уже хватает. Дёшево, сердито, быстро. И бэкап редактору настроить на всяк случай не помешает.
PS. Начинай с фронта, так проще. На бэкенде тупо покорми «затычками» (стабами, моками, etc.), возвращающими одно и то же, а уже потом реализовывай. Сэкономишь туеву хучу времени на его переписывание. И главное, если чё не так — можно быстро подправить пока пишешь фронт. И даже протестить после, не написав бэкенда, и даже показать заказчику.
И маленький совет: не удаляй эти затычки когда код пойдёт в продакшен. Лучше взведи флаг, позволяющий на них переключиться, и используй его для тестов, в том числе удалённо. Поможет быстро выяснить на какой стороне бага, на фронте, на бэке, или на звеньях между.
Благодарю, мне такое как раз пока подойдет.
по стадиям:
1. гугл дока одна общая файлень (правят те кому можно)
(1.1. когда таблицы становятся слишком большими/значимыми — докидываешь гугл таблицу, например для проектной схемы БД «по бедному по простому (удобно для полей-которые-наверное-нужно-еще)
2. +схемка «всей вселенной» (когда уже одного текста мало), 1 файлик
3. проектная Вики на бесплатном движке (становится нужной когда «люди приходят и уходят»)
Это проверено — это работает.
По супербедному/быстрому (зато всегда под рукой) можно исхитриться запинать все это дело в Evernote.
Гуглодока тормозная и глючащая. В какой-то момент может оказаться что вы видите разные версии. А уж баги на сохранении...
хз я лично не сталкивался. знаю есть баги если таблицу к примеру с мобильного обновляют одни, а с десктопов — другие
зато out-off-the-box и можно втыкать на смартфоне даже у бусіку додому до жмеринки. и версионность еще, что бывает спасает.
Можно на каждое «сделано» заводить небольшую трелло карточку с названием, описанием и ссылкой на изменения в коде, например.
Wiki файлы в репозитории? Диаграммы? Google Docs. Витамины для памяти попить.
кушаю грецкие орехи:)...
Отдел документации на зарплате, который выпускает печатный мануал на тыщи страниц
это на предприятиях, а простому «джедаю» как быть ?
Либо документацию надо писать, либо код — лучшая документация. Других вариантов нет
вчера наткнулся на интересную статью о том какие требования к формату сообщений для коммитов на Angular OpenSource, взял на вооружение, это должно решить 80% моих «проблем»
поделитесь ссылкой