The following text is a partial translation of the original English article, performed by ChatGPT (gpt-3.5-turbo) and this Jekyll plugin:
Я каждую неделю читаю несколько технических спецификаций от наших текущих и потенциальных клиентов, и есть одна вещь, которую я больше не могу терпеть; мне нужно об этом написать: 99 процентов документов, которые я читаю, не имеют глоссариев, и из-за этого их очень трудно читать и усваивать. Даже когда они имеют глоссарии, их определения терминов очень неопределенные и двусмысленные. Почему это происходит? Разве мы не понимаем важность общего словаря для любого программного проекта? Я не уверен в причинах, но это то, что должен делать архитектор программного обеспечения, когда он начинает проект - создать глоссарий.
Я пытаюсь написать что-то уникальное по этой теме, но все, что я могу сказать, настолько очевидно, что я сомневаюсь, что кто-то будет заинтересован в его прочтении. В любом случае, я попытаюсь.
Глоссарий (также известный как словарь) - это список терминов, используемых в проекте, который обычно включается в начало технического спецификационного документа. Идеально, каждый технический термин, использованный в документе, должен быть кратко объяснен в глоссарии. Наличие глоссария помогает всем, кто работает с документом, быстро понимать друг друга и избегать недоразумений. Кроме того, подробный и точный глоссарий экономит много времени читателя.
Итак, почему не пишут глоссарии? Я вижу несколько возможных причин (обычно они сочетаются):
Мы умнее, чем это. Некоторые люди думают, что глоссарии для новичков. В конце концов, зачем мне объяснять, что такое PDU? Любой серьезный сетевой инженер должен понимать, что это означает “протокольная единица данных”. Если вы не понимаете, изучите этот вопрос и вернитесь к нам на работу. Наша команда работает только с хорошо образованными инженерами. Вы должны понимать, что означают PDU, ADC, TxR, IPv6, DPI, FIFO и СССР (шутка!). В противном случае вы не достаточно талантливы, чтобы быть с нами. Не нужно говорить, что такое отношение может возникнуть только у тех, кто не имеет представления о том, что он делает. Хороший инженер всегда помнит, что если получатель не понимает сообщение, это вина отправителя.
Нам не нужны эти формальности. Серьезно, зачем нам тратить время на написание глоссария, если все понимают все наши термины без него? Мы работаем вместе несколько лет, так что мы все знаем, что такое DPI и FIFO, и мы знаем, что такое “запись” и “данные о времени”. Зачем заморачиваться с глоссарием, которое не принесет нам дополнительной бизнес-ценности? Я видел множество технических встреч очень зрелых и “хорошо организованных” команд, которые тратили часы на бессмысленные обсуждения просто из-за разных пониманий одного и того же термина. Глоссарий не является формальностью; это ключевой инструмент программного архитектора и всех остальных участников команды.
Мы предпочитаем работающее программное обеспечение полной документации. Это говорит Agile Манифест, и это правда. Но ключевое слово здесь - “полная”. Нам не нужна полная документация, но нам нужен глоссарий. Это ключевой элемент любого проекта, и его нельзя заменить работающим программным обеспечением. Ни одно работающее программное обеспечение не поможет нам понять, что такое “заголовок” и “сигнал данных”, если нет простого и ясного объяснения об этом.
У нас нет времени. Мы развиваемся слишком быстро и каждый день проводим мозговой штурм, поэтому концепция часто меняется. У нас просто нет времени для документирования своих мыслей. Мы все понимаем друг друга, и в этом красота быть гибкими. Нет, это не красота. Это является недисциплинированностью и отсутствием элементарного управленческого навыка. Отсутствие глоссария - личная ошибка программного архитектора, и тут нет никаких оправданий.
Все наши термины хорошо известны каждому. Серьезно, нужно ли нам документировать, что такое TCP/IP и FIFO? Это то, что учат нас в школе. Все понимают это, не так ли? Да, некоторые термины хорошо известны. Но в чем проблема добавить их в глоссарий с несколькими словами и ссылкой на статью в Wikipedia? Это займет всего несколько минут времени архитектора, но сделает жизнь проще для всех участников проекта, как сейчас, так и через несколько лет.
В заключение, нет никаких оправданий для отсутствия глоссария в любом программном проекте. И это личная ответственность программного архитектора поддерживать этот документ (или раздел) в актуальном состоянии.
Надеюсь, я не был слишком очевидным выше.
Translated by ChatGPT gpt-3.5-turbo/42 on 2023-11-17 at 17:13
