Какие моменты отдела разработки, должны быть задокументированы?

Question

[Виктор Янышев]

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

Например, нужно документировать:
1. Деплой
2. Поднятие хостов ( например столкнулся с тем что хосты на дев кординально поднимаются по разному на продакшн, итог потеря времени)
3. Соглашение по синтаксису
4. Структура проектов (само собой разумеющиеся)
5. Работу отдельных скриптов, решающие задачи например с синхронизацией бд.
6. Нюансы работы с админкой приложения

Что ещё необходимо задокументировать как инструкции к действию?

В копилку информации к этому вопросу хотел бы также добавить этот вопрос Схема CI сборки и публикации проектов, верно ли?

Answer 1

[Максим Федоров]

Чем больше, тем лучше (ваши пункты подходят более чем), но без фанатизма, чтобы работа в чтение христоматий не превратилось

Где затыки могут быть или сложности -- я будучи 2 недели на работе при установке проектов компании написал инструкции по локальному развертыванию -- тк 3 из 4 проектов с затыками и требовалась помощь старших, теперь не требуется

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

Описание тестов
Что тестировать, как, а что не возможно (в силу религии или рахдолбайства) затестить, но важно обращать внимание

Answer 2

[ой всё]

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

Answer 3

[kn0ckn0ck]

Отделу разработки грех не стремиться к самодокументируемости. У вас так быстро растет отдел, что нет времени объяснить новчику в теч. пары часов как все устроено? Или у вас процесс разработки/деплоя вылит из гранита, что за устаревание/обновление докуметации вы не паритесь?

1. Jenkins Pipeline (или Gitlab) - пример самодокументируемого деплоя
2. аналогично п. 1
3. Есть уже куча готовых, просто дать ссылку
4. Показать и объяснить устно, чтобы снять сразу возможные вопросы/критику/непонятки
5. Единственное что имеет смысл задокументировать (что редко меняется) - архитектурные особенности. Внутри каждого скрипта должны быть либо комментарии, либо код должен быть самодокументируем. Если нужно описать "клей", то почему бы не использовать Ansible/Chef для этих целей?
6. "Никогда не нажимай эту красную кнопку..." - ну вы знаете, что затем последовало.