📋
Документация в 1С: вы ее писали, вы ее читали, вы ее видели?Друзья, рабочая неделя в самом разгаре, поэтому можно сделать маленький перерыв за чашечкой кофе и поговорить о документации в 1С. Отлично! Ведь нет ничего прекраснее, чем разбор темы, от которой у всех сразу начинают чесаться руки и появляется желание переключиться на что-то более увлекательное... например, на просмотр сериала про налоговых инспекторов 😁
Перед нами семь ключевых вопросов, ответив на которые, можно смело утверждать, что сформировано понимание — для чего же нужна нам в 1С документация:
1️⃣ Какая цель документации?Краткий ответ: «Создать иллюзию, что мы понимаем, что делаем» — так честно ответил бы каждый второй аналитик 1С после третьей чашки кофе на 105-ый день проекта внедрения 1С.
А если серьезно, то цель документации — сделать так, чтобы через полгода вы сами поняли свой код/мысли/посылы, а коллеги не устроили вам самосуд за "творческий беспорядок" в проекте. По сути, это ваша страховка от фразы: "Кто это писал?! А, это я...".
2️⃣ Для чего документация?Документация
нужна для того, чтобы (и это лишь некоторые варианты, на самом деле их гораздо больше):
- Передать проект новому разработчику без риска получить от него месть.
- Объяснить бизнесу, почему "простая" доработка займет 3 недели.
- Защититься от менеджеров фразами типа "Это не было в техзадании!".
Как говорится: "Нет документации — нет проблем. Есть документация — проблем в разы больше".
3️⃣ Для кого документация?Краткий ответ: для всех и для никого одновременно! 😋
- Для разработчиков — чтобы понимать, что творили предшественники.
- Для пользователей — чтобы не звонили каждые 5 минут с вопросом "А где кнопочка?".
- Для менеджеров — чтобы было что показать клиенту и сделать вид, что деньги потрачены не зря.
- Для всех-всех-всех!
Парадокс: документацию пишут те, кто в ней не нуждается, для тех, кто ее не читает.
4️⃣ Кто пишет документацию?Краткий ответ: вот тут начинается самое интересное! По идее —
технический писатель.
🔜 Кто это такой в 1С?!? 🔙
На практике:
- Программист — со слезами на глазах и проклятиями.
- Аналитик — который "быстро накидает" на 50 страницах.
- Стажер — потому что "ему надо набираться опыта".
- Тот, кто не успел сбежать с совещания 🤩
А, технический писатель на 1С-проекте — это как единорог: все о нем слышали, но мало кто видел.
5️⃣ Что содержится в документации?Идеальная документация содержит:
- Описание того, что должна делать система.
- Описание того, что система делает на самом деле.
- Объяснение, почему эти две вещи не совпадают.
- Список людей, которых можно привлечь к разъяснению первых трех пунктов.
А еще: техзадания, инструкции, схемы интеграций, и обязательно — раздел "Известные проблемы", который занимает 80% всего документа.
6️⃣ Критерии оценки документации?Хорошая документация — это когда:
- Новый сотрудник может разобраться в проекте за неделю, а не за месяц.
- Количество вопросов "А как это работает?" снижается с 50 до 30 в день.
- Заказчик перестает говорить "Но мы же договаривались по-другому!".
Плохая документация — когда проще переписать систему с нуля, чем понять, как она работает.
Критерий оценки: "документация как вино: чем старше, тем менее соответствует действительности" ☕️
7️⃣ Как правильно оформлять документацию?Золотые правила оформления документации в 1С:
- Пишите так, будто читать будет ваш злейший враг, который ищет повод вас уволить.
- Используйте скриншоты — картинка стоит тысячи слов объяснений.
- Структурируйте информацию — заголовки, списки, таблицы. Сплошной текст читать никто не будет.
- Обновляйте регулярно — документация должна быть как код: живой и актуальный.
- Избегайте фраз типа "очевидно", "просто", "легко" — то, что очевидно вам, для других может быть китайской грамотой.
🔸
Если тема интересна приходите 24 октября на Желтую конфу! Подробнее о программе и регистрация тут.
❔
Ну а как вы считаете, документация — это зло или польза для всех?
