Ты точно умеешь писать документацию? 📝
Все думают что умеют писать. Русский у всех же был в школе? Из букв составляем слова, из слов текст и описание готово, принимайте доку.
Но часто аналитики сами попадают в ловушку — написал казалось бы простое понятное описание, а читать это по итогу вообще невозможно 🙂
Вот одни из самых частых ошибок:
1. Внутри много много мяса, мало теста.🥟
Длинные нагромождённые предложения, где много слов и смысл быстро теряется.
Лучше несколько коротких предложений, чем одно гигантское.
2. Жаргон в документах 🤓куку епта
Если в чате написать "пофиксить", "задизейблить", "дропнуть" и.т.д — ок.
То в документации такое уже не ок.
Кто-то может не знать ваших слов или неправильно их интерпретировать. Лучше исключить разночтение заранее.
3. Масло маслянное🤩
Тавтология и бессмысленные повторы только ухудшают восприятие. Если можно написать короче — пишите короче.
4. Противоречия между разделами⚡️
В начале написал одно, в другом разделе уже другое. Лучше не торопиться и лишний раз перечитать документ/задачу/письмо, перед тем как отдавать.
Криво напишите -> Разраб криво сделает -> Тестер криво проверит -> Баг
5. Термины без расшифровки 😏
У вас могут быть специфичные термины внутри продукта, которые знают не все. Через полгода новый человек откроет вашу документацию и вообще не въедет что и как вы тогда реализовывали.
Используете локальный термин — лучше расшифруйте.
P.S. Всё никак не могу дойти до книги «Пиши, сокращай», так и просится.
Часто ловите такое за собой или за коллегами? Я лично постоянно встречаю первый и третий пункт👇
IT АНАЛитика | Подписаться
Все думают что умеют писать. Русский у всех же был в школе? Из букв составляем слова, из слов текст и описание готово, принимайте доку.
Но часто аналитики сами попадают в ловушку — написал казалось бы простое понятное описание, а читать это по итогу вообще невозможно 🙂
Вот одни из самых частых ошибок:
1. Внутри много много мяса, мало теста.🥟
Длинные нагромождённые предложения, где много слов и смысл быстро теряется.
Плохо🤡:
Сервис проверки клиента предназначен для осуществления проверки корректности введённых пользователем данных в рамках процесса оформления кредита с учётом действующих ограничений и бизнес-правил»
Хорошо🤩:
Сервис проверяет данные клиента при оформлении заявки на кредит.
Лучше несколько коротких предложений, чем одно гигантское.
2. Жаргон в документах 🤓куку епта
Если в чате написать "пофиксить", "задизейблить", "дропнуть" и.т.д — ок.
То в документации такое уже не ок.
Кто-то может не знать ваших слов или неправильно их интерпретировать. Лучше исключить разночтение заранее.
3. Масло маслянное🤩
Тавтология и бессмысленные повторы только ухудшают восприятие. Если можно написать короче — пишите короче.
«Система должна обеспечивать возможность предоставления доступа пользователям» → достаточно «Система предоставляет доступ пользователям».
«Происходит процесс авторизации пользователя» → «Пользователь авторизуется».
«Выполнить осуществление проверки данных» → «Проверить данные».
«Производится выполнение логирования ошибок» → «Ошибки логируются».
«Происходит процесс сохранения данных в базу данных» → «Данные сохраняются в базу».
4. Противоречия между разделами⚡️
В начале написал одно, в другом разделе уже другое. Лучше не торопиться и лишний раз перечитать документ/задачу/письмо, перед тем как отдавать.
Криво напишите -> Разраб криво сделает -> Тестер криво проверит -> Баг
5. Термины без расшифровки 😏
У вас могут быть специфичные термины внутри продукта, которые знают не все. Через полгода новый человек откроет вашу документацию и вообще не въедет что и как вы тогда реализовывали.
Используете локальный термин — лучше расшифруйте.
P.S. Всё никак не могу дойти до книги «Пиши, сокращай», так и просится.
Часто ловите такое за собой или за коллегами? Я лично постоянно встречаю первый и третий пункт👇
IT АНАЛитика | Подписаться