Комментарии 52
Спасибо, статья по делу.
Я, помню, как-то читал постановку, в которой широко использовались возвратные формы,
страдательный залог. В итоге было совсем не очевидно, что часть описанной работы
по наполнению базы данных выполняют операторы.
Чтобы выяснить, по каким алгоритмам надо заполнять базу,
я обратился к аналитику-архитектору, написавшему постановку,
и неожиданно выяснил, что в этой части базу должны заполнять люди-операторы.
Чтобы это выяснить, мне пришлось пойти на поклон, просить разъяснений,
извиняться за своё недопонимание и делать "ку"-приседания.
И тут я разовью мысль про неопределённость в постановках.
Если постановки кто-то пишет непонятно, значит это кому-нибудь нужно.
Непонятно написал, к тебе ходят за уточнениями, ты снисходительно отверзаешь уста свои и величественно разъясняешь. Тебе кланяются и благодарят.
В итоге у аналитика-постановщика возникает ореол незаменимого эксперта.
Поэтому, я считаю, если в постановке программа выполняется и база заполняется,
то это неспроста: это кому-нибудь нужно, чтобы читатель постановки или документации потратил часть социального своего капитала на поклоны и запросы на уточнение.
Таким образом на ровном месте писатель куёт свой социальный капитал, а читатель тратит.
И ведь не предъявишь претензию: формально подходя, в постановке всё написано! А если читатель "элементарных вещей" не понимает и "элементарные вещи" ему, дураку-коллеге-читателю, надо разъяснять, то это не писателя проблемы, это коллега-читатель тупенький попался. Кстати, а почему такой непонятливый читатель всё ещё наш коллега?
Мой поинт в том, что авторы постановок задач используют неопределянные формы и возвратные формы не случайно. Если в предложении на русском языке управление потеряно, то в корпоративном влиянии управление поднято.
Поначалу пытался прочитать комментарий как стих.
На каждый поклон пишем подробный фидбек, с примерами, теорией, etc
Через N поклонов поднимаем вопрос с руководством - команда тратит P часов на выяснение одного и того же, ситуация не меняется, мы даже давали подробный фидбек. В связи с этим стоимость разработки продукта возрастает на X, сроки сдвигаются на Y.
После этого забить и не переживать. Подобное в корпорате лечится подобным
Спасибо за то, что подняли актуальную тему!
Иной раз в самом деле непонятно, кто что должен делать, потому что написано, что все как будет делается само.
Хорошо, если отдельно описано, кто что делает. Но часто нет, и пригодится играть в угадайку,
Текст статьи прочитан. Спасибо.
С платежом, я думаю, это не исключение, а продолжение того же правила: страдательный залог с опусканием агенса запутывает читателя, не давая понять, кто выполнил действие, и именно этого авторы и добиваются. Потому, что «Мы отклонили ваш[е] платёж[ное поручение]» или «Мы отказали вам в кредите» слишком уж похоже на посыл понятно куда. А так, и пользователь послан, и агенса нет.
Ещё возможно размывание, когда слова не склоняются. Попробую провести примеры, не гарантирую, что они будут удачны, но попробую донести суть.
"Вася принёс щенка" - тут всё понятно. Русский язык позволяет написать "Щенка принёс Вася" в определённых ситуациях.
А если у нас фраза типа "AMD купила ATI", то в некоторых случаях может быть неочевидно, кто кого купил. Особенно если текст написан не простым техническим языком, а цветисто, витиевато, с применением сложных конструкций предложений и редко применяемых литературных приёмов построения фразы. Я сам встречал такое: заголовок новости - "Grand Palace купил Проценко", и гадаю, то ли некий условный инвестор Проценко купил отель Грэнд Пэлас, то ли отель Грэнд Пэлас заключил долгосрочный контракт с каким-нибудь музыкантом или оформителем Проценко, перехантив его к себе на работу. Особенно часто эта путаница получается из-за ужасной моды переставлять слова в названии с целью упрощения алфавитной сортировки: по-русски должно писаться "Конфеты Мишка на Севере", а пишут "Мишка на Севере конфеты", "Лампа люминисцентная" вместо "Люминесцентная лампа" и прочие подобные уродства. Это проникает и в повседневные построения фраз, и когда слова не склоняются, порой невозможно определить субъект и объект действия.
"AMD купила ATI"
В русском языке есть правило, о котором многие не помнят. Если форма именительного и винительного падежей совпадает, то именительный (подлежащее) всегда(!) ставится на первое место. В вашем случае покупку совершила AMD.
"Лампа люминисцентная" вместо "Люминесцентная лампа"
Первый вариант полностью соответствует ГОСТ 2.104-2006 " Основные надписи.
А зачем в ГОСТ проник этот исковерканный порядок слов? В русском языке в общем случае нормально писать сначала прилагательное, описывающее свойство, а затем существительное. Думаю, изменённый порядок слов пришёл из словарей, где в угоду быстрому алфавитному поиску нужного термина ставили на первое место существительное. Но одно дело - справочник аптекаря, где будет "дуба кора" и "расторопша пятнистая", и другое дело, когда так коверкается публицистический стиль.
Котлеты бабушкины останки... Vs Останкинские бабушкины ко...
Ставить слова в порядке важности имеет смысл, если никто не гарантирует, что они все вместятся на ценник/надпись/т.д.
Но писать по ГОСТу публицистические статьи - это действительно что-то странное.
Потому что из основной надписи название попадёт в спецификацию, а в ней удобнее искать нужную позицию, когда существительное (которое характеризует самое важное свойство) идёт первым.
В ГОСТ этот стиль проник по простой причине: от общего к частному. Лампа ведь может быть люминесцентной, ультрафиолетовой, инфракрасной, накаливания, газоразрядной металлогалогенной, и т.п. Поэтому в первую очередь это лампа, а какая именно — пишем уже потом. Отсюда же вытекает удобство сортировки однородных названий:
- лампы газоразрядные люминесцентные
- лампы газоразрядные ультрафиолетовые
- лампы газоразрядные монохроматические
и для них всех, например, придумали какой-то общий документ, например, технические условия.
За областью определения ЕСКД писать как в ЕСКД, конечно же, не обязательно. :)
del
Да про пассивный залог, и еще примерно 40 правил по написанию технических требований, люди знают. И даже существует технический комитет(ы) который систематизирует требования на требования (sic!). Вот например на Хабре заметка об этой деятельности Примеры формулировок требований по правилам руководства по написанию требований от INCOSE
«Вход в автобус осуществляется через переднюю дверь»
Язык Эсперанто примерно к тому же приучает, как и во всех основанных на латыни языках нужно обязательно указывать кто что-то делает. Если просто на русском пишем "конфигурируют", то на эсперанто будет не достаточно написать konfiguracias, нужно уточнить oni konfiguracias (то есть уточнение что кто-то конфигурирует). Да и страдательный залог в эсперанто называется аккузативом и в конце слова ставится -n, тогда сразу понятно кто над чем или кем совершает действие. Например, "конфигурируют маршрутизатор" на эсперанто oni konfiguracias enkursigilon. В этом плане эсперанто как простой и лаконичный язык очень хорошо подходит в качестве технического языка и международного языка технической документации.
Чисто для информации (по смыслу не существенно) -- аккузатив - это не страдательный залог, а винительный падеж. Страдательный залог в эсперанто есть (enkursigilo estas konfiguraciata), и с ним те же проблемы (если не указать 'de ...', т.е. кем).
А в языке Идо -n нужно ставить только при непрямом порядке слов
В английском языке вообще есть общее правило хорошего стиля - по возможности избегать "passive voice", т.е. страдательного залога.
Кстати, из-за того, что в переводных русскоязычных руководствах бывает огромное количество вот таких словесных выкрутасов, или конструкций типа "А маршрутизирует Б" (при том, что и А, и Б - англоязычные термины в непонятно каком падеже), мне часто было проще прочитать оригинал на английском (который я знаю на уровне примерно А+), в котором всегда понятно, кто "-ed" by каким "-ing" ))
Автору респект! Эта статья должна стать обязательной для изучения всеми преподавателями и техническими писателями. Да и вообще всеми. Часто наблюдаю как люди не понимают друг друга и страдают именно из-за вот этого страдательного залога. Особенно это проявляется в преподавании. Причем плохо даже не то, что часто какая-то фраза непонятна, а то, что её поймут неправильно.
А если вместо вопроса "Что делает?", использовать вопрос "Что сделает?".
"Переключатель переключится в положение ON" - подразумевается автоматическая работа переключателя. Или "после нажатия на кнопку, база заархивируется". Мне кажется, тут все вполне понятно.
Значение параметра может задать как система, так и пользователь.
Собственно, в том и проблема. Зачастую на момент написания документации вообще непонятно кто и как будет задавать параметр. Это может быть пользователь, система, конфиг файл или инопланетяне.
И появляется два стула: Писать документацию по кусочкам или надеяться на то что кто-нибудь когда-нибудь будет переписывать всю доку.
Какие-то высосанные из пальца (можно я не буду уточнять кем?) примеры, которые предсказуемо оказываются негодными, например:
В зависимости от настроек, либо резервное копирование выполняется системой автоматически, либо его при необходимости выполняет пользователь
<...>
На первый взгляд тут всё понятно и однозначно — чётко указано, кто и что делает.
Ничего тут не понятно: за это при необходимости авторов следует четвертовать, еще до того, как будут расстреляны адепты страдательного залога. Кем определяется (привет страдательному залогу) эта необходимость? Как о ней узнает пользователь? Не говоря уже о том, что первое "либо" лишнее.
Существует разделительный союз "либо… либо".
"При необходимости" мне тоже бросилось в глаза. Но потом я присмотрелся и понял, что смысл тут полностью локализован во второй ветке: "когда ему (пользователю) надо"
Существует также понятие лексической сочетаемости и уместности употребления. В данном случае употребляется единичное "либо", а не "либо - либо".
Я процитировал не тот фрагмент (хотя сути это не меняет), вот предлагаемый автором "правильный":
«Система автоматически выполняет резервное копирование, если это задано настройками. Иначе пользователь при необходимости самостоятельно выполняет резервное копирование».
То, что копирование выполняется пользователем - очевидно из обоих вариантов текста, неочевидно - кем и как определяется необходимость и как о ней узнает пользователь. Система не выполняет копирование автоматически - это не условие возникновения необходимости, т.к. явно указано: иначе (когда система не выполняет копирование автоматически) и при необходимости (при наступлении еще неких неуказанных условий).
А если заменить "при необходимости" на "в случае необходимости"? Станет понятнее, что именно пользователь определяет, когда этот случай наступает?
Нет, конечно, с какой стати? Необходимость она обезличенная, непонятно кому это необходимо и почему. Если так уж надо остаться в рамках заданной конструкции, то лучше заменить на "по желанию".
А если не ограничиваться этой конструкцией, как можно сформулировать лучше?
А то ведь "по желанию" тоже не вполне точно: пользователь может и не желать выполнять резервное копирование и вообще в гробу его видать, а необходимость есть.
Ну так всё правильно же: если пользователь в гробу видал эти бэкапы и не желает их делать, то они и не делаются. Даже если есть необходимость в них.
А тут надо плясать именно от этой необходимости - откуда она берется: из здравого смысла, например, или из требований внутренней организационно-распорядительной кухни, а то и из требований законодательства. Отсюда и формулировки формулируются. А просто "по необходимости" - это ниочем, имярек не увидел необходимости - значит ее не было, а что прос*али все полимеры бэкапы - так это руководитель ССЗБ: не разработал нормативку и расписал инструкции вилами по воде.
Совок археолога наткнулся на что-то твёрдое. Из земли показалась колонна 5 века...
«После нажатия на кнопку выполняется сжатие базы данных».
Этот пример может означать следующее:
После нажатия на кнопку пользователь должен запустить сжатие базы данных.
После нажатия на кнопку система выполнит сжатие базы данных.
После не значит вследствие. Я бы предложил "нажатие кнопки запускает сжатие базы данных".
Еще есть вариант использования формы завершенного времени для глагола если действие выполняет система, а не пользователь/администратор:
«После нажатия на кнопку выполняется сжатие базы данных». - После нажатия на кнопку выполнится сжатие БД.
«После этого переключатель „Методы“ устанавливается в положение „Расширенный“». - После этого переключатель "Методы" установится в положение "расширенный".
«Перед обработкой файла создается его резервная копия». - Перед обработкой файла создастся его резервная копия.
ИМХО, во всех трёх вариантах очевидно, что действия будут выполенны системой без (и даже вопреки) участия человека.
Актуальная тема.
Всегда раздражало "бытие определяет сознание".
Я побуду адвокатом дьявола, т.к. часто использую пассивный залог в документах на английском, хотя я его сам не шибко люблю. Для начала отмечу, что техническая и пользовательская документации — это две разных сущности. Первая описывает работу системы, а вторая указывает, как с ней взаимодействовать. Ваша статья применима к текстам второго типа.
Вы не сможете заменить пассивный залог в документации или научных текстах, например, в описании методологии. Причина простая: там не важен актор, важно действие или результат.
Там будет что-то вроде: "Образец располагается над нагревательным элементом и вращается для обеспечения равномерного нагрева". Потому что на самом деле могло быть так: лаборант держал образец над свечкой клещами и вращал так быстро, как мог. А читатель может достигать результата любыми доступными ему средствами. Стоит только написать в методологии "мотор вращает образец", и сразу будут вопросы: а что за мотор, а как вращает, а мне обязательно нужен мотор или лаборант справится?
Тут главное соблюдать баланс — не переборщить с пассивным залогом и не добавлять акторов, когда они не важны читателю.
Вроде очевидно, что страдательный залог используется тогда, когда важен объект и действие, которое произведено над объектом. При этом не важен актор.
Если актор важен, то страдательный залог использовать не стоит.
Не сильно сократил Вашу статью? )
Разрешите позанудствовать?
«Процесс завершается, как только все папки будут проверены на наличие инфицированных файлов».
«Приложение завершает процесс после проверки всех папок на наличие инфицированных файлов».
Вроде два одинаковых по смыслу предложения. Но нет. «Как только» и «после» сильно разные по скорости выполнения, и по смысловому оттенку условия. Сравните:
«Спасение корабля началось, как только обнаружили воду в трюме»
«Спасение корабля началось после обнаружения воды в трюме»
Ко второму предложению так и тянет добавить «но было поздно».
Вторая пара:
«После этого в программе автоматически выполняется обработка данных».
«После этого программа автоматически обрабатывает данные»
А давайте так:
«После снегопада в управляющей компании производится уборка снега»
«После снегопада управляющая компания производит уборку снега»
Разница чувствуется?
«Кто на ком стоял?» Про страдательный залог в технической документации