Не слишком ли сложно следовать руководствам по стилю для технического письма?

Нет, следовать книге стилей не является излишеством. Как говорили другие, вы консультируетесь с ним по мере возникновения вопросов и учитесь по ходу дела; вы обычно не читаете его от корки до корки. Мы все прикрепляем заметки к часто посещаемым разделам. Поскольку вы взяли на себя труд задать свой вопрос, вас, очевидно, беспокоит отсутствие последовательности внутри вашей компании.

Кроме того, поскольку вы много пишете для своей работы, скорее всего, вы уже следуете стилю. Я бы посоветовал вам начать составлять документ, включающий все, что вы постоянно ищете, и создать собственное руководство по стилю. Кто знает, может быть, ваша компания когда-нибудь примет ваше руководство! (Один совет: при составлении собственного руководства отметьте, на каком авторитетном источнике вы основываете каждое «правило», чтобы при необходимости можно было вернуться к нему.)

Моя компания следует The Associated Press Stylebook , за исключением случаев, когда они этого не делают. У нас есть документ Word с исключениями, который обновляется по мере принятия решений. (В файле всегда отмечается дата изменения правила.) Кроме того, AP иногда меняет свой стиль, и моя компания должна решить, согласны ли они. Например, в прошлом году AP заменила электронную почту на электронную. Моя компания этого не сделала.

Для документации, которая будет опубликована за пределами вашей организации, обычно важно следовать руководству по стилю (практически любому), чтобы вся документация читалась одним «голосом», даже если она была написана кучей разных людей. Как отмечает Лорен Ипсум, вы не читаете руководство по стилю от корки до корки, а скорее консультируетесь с ним по отдельным пунктам. (Однако вам нужно ознакомиться с тем, какие моменты он охватывает.)

Я сказал, что это «обычно» важно; вы должны сначала задать вопрос, прежде чем приступить к принятию руководства. Существует практика «каждый сам за себя»; все так, потому что это действительно не имеет значения для ответственных людей, или только потому, что вопрос никогда не поднимался? Если для них это не важно, то вам нужно доказать, что это имеет значение пропорционально затратам на внедрение новой практики. Покупная цена книги — шум; цена будет заключаться в изменении рабочих привычек каждого. Если клиенты (или другие важные люди) увидят эту документацию, то это вполне может быть легкой презентацией; если он используется только членами вашей команды, это может не иметь значения (как бы больно мне, как писателю, говорить это).

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

Кажется, что руководство по стилю — это то, что вы надеетесь создать и внедрить в масштабах всей компании, что-то, что стандартизирует такие вещи, как разделы в отчете или руководстве пользователя, используемые шрифты, использование логотипа и товарного знака, программное обеспечение, которое будет использоваться для создания документации, и дизайн шаблона. стандарты. Поищите в Интернете «руководство по техническому стилю», и вы найдете примеры.

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

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

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

Совсем не перебор. Однако « Чикагское руководство по стилю» на самом деле не идеально подходит для технического письма (и предназначено для ознакомления, а не для чтения от корки до корки). Это хорошее руководство по общему официальному письму для американцев. Для более международной аудитории эквивалентом является «Оксфордское руководство по стилю» (также известное как «Правила Нью-Харта» , также опубликованное как половина Оксфордского руководства по стилю ).

Основная проблема с Чикаго заключается в том, что его редакторы категорически против использования логического цитирования (т. е. включения в кавычки ничего, чего не было в исходной цитате), кроме «текстовой критики» и «компьютерного кода и команд». В остальном они не рекомендуют ничего, кроме пунктуации цитат в стиле американской журналистики и художественной литературы, в которой точки (стоп, точки) и запятые всегда помещаются внутри кавычки, даже если они логически не принадлежат ей. Это ужасная идея в любой технической или другой точной форме написания, хотя она по-прежнему поддерживается AP Stylebook и другими американскими руководствами по журналистскому стилю.

Если вашей работой является техническое письмо, я бы посоветовал иметь руководства по Чикаго , Оксфорду и AP (а также любые другие руководства по стилю, которые могут вам понадобиться, например, юридические Bluebook и Redbook , а также оксфордский эквивалент OSCOLA , который является бесплатным PDF -файлом). и/или руководства по научному/медицинскому стилю CSE , AMA и APA ). Адаптируйте свой стиль по мере необходимости. Для делового общения с американцами используйте Chicago ; для PR-материалов, предназначенных для американцев, используйте AP ; для международной аудитории положитесь на Оксфорд(также при цитировании с высокой точностью, например, введенных команд или меток на элементах управления устройством). Обратитесь к CSE и т. д ., если это необходимо для написания научных работ. Иногда вас также могут попросить соблюдать Руководство по стилю MLA для некоторых целей. Все эти книги являются хорошим капиталовложением для любого профессионального писателя документальной литературы. Как и обновление их до новых выпусков по мере их выпуска; иногда изменения значительны (хотя для распространения требуется несколько лет). Эффективное использование языка — это движущаяся цель.

Купить? Да. Я не думаю, что вам нужно читать его от корки до корки, если только вы не серьезный специалист по языкам, который читает словари для развлечения. ::кашель::кашель::

(Вытащив мой 14-й выпуск для справки...)

Я постараюсь прочитать как можно больше «Частей книги» и «Подготовки рукописи», прежде чем ваши глаза помутнеют. Если вы не читаете чью-то работу, вы можете просмотреть раздел корректуры. "Дизайн и типографика" тоже неплохо бы почитать.

Все остальное, что вы можете найти, когда столкнетесь с этим: я использую серийную запятую? В этом предложении есть «который» или «тот»? Как процитировать веб-сайт в библиографии?

Я не думаю, что следовать руководству по стилю — это излишество. Очень полезно иметь авторитетный ответ на такие вопросы, как пользоваться электронной почтой или электронной почтой , а не искать их десятки раз или спорить о них с другими людьми. Тем не менее, CMOS, вероятно, слишком подробна для ваших нужд, и я, конечно, не стал бы читать ее от корки до корки. Даже будучи человеком, вся работа которого заключается в написании текстов, я бы не стал сидеть и читать руководство по стилю от корки до корки. Для инженера-электрика я не думаю, что это хорошее использование вашего времени.

В настоящее время на моей книжной полке у меня есть The AP Stylebook и Microsoft Manual of Style. Мне нравятся оба, хотя AP не использует последовательные запятые, и лично мне нравятся последовательные запятые. Microsoft очень полезна для инструкций по программному обеспечению, потому что она определяет, как форматировать названия кнопок, окон, экранов и меню.

На самом деле может быть полезнее написать собственное руководство по стилю и создать шаблон для документов, которые вы пишете чаще всего. Руководство по стилю может быть простым списком стилевых решений; это не должно включать все под солнцем. Когда я пишу руководства пользователя, я перечисляю все части интерфейса и способы оформления этих терминов. (Например, если в приложении есть небольшая 3D-карта для навигации, я отмечаю, как она называется: мини-карта, мини-карта, 3D-карта, навигационная карта или как-то еще.) иметь более одного стандартного написания или расстановки переносов. Каждый раз, когда у меня возникает вопрос о термине, когда я пишу или редактирую, как только я разрешаю его, я добавляю его в список.

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

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

Если документация будет когда-либо написана одним человеком и прочитана одной и той же группой людей, эта документация не требует стиля (при условии, что это внутренняя документация, не предназначенная для клиентов). Пока обе стороны это понимают, это может работать, хотя новичкам может потребоваться некоторое время, чтобы понять. Если написать его на библейском греческом языке для этой ситуации, то с этим проблем не возникнет.

Однако почти вся документация, даже внутренняя, будет написана более чем одним человеком и со временем прочитана разными людьми. Это могут быть инструкции по тестированию, но аудиторам QA также может понадобиться их увидеть. Учебные документы могут быть первоначально предназначены для определенных групп, но затем они могут быть сохранены для новых людей. Таким образом, некоторая форма стандартов является хорошей идеей, хотя они могут быть не такими строгими, как для внешних пользователей.

Цель состоит не в том, чтобы все всегда было последовательно и профессионально, а в том, чтобы новые люди могли правильно понимать и интерпретировать документацию. Так что мелкие опечатки не так важны, а ясность и последовательность.

AP очень похож на Чикагское руководство по стилю , но гораздо проще в использовании. Зачем идти против течения? Вы собираетесь охватить как можно более широкую аудиторию с помощью AP, что, я считаю, должно быть здесь конечной целью.

CMOS не представляет для вас реальной ценности. И я пожизненный член IEEE, но они делают много бюрократических вещей, которые не представляют реальной ценности для членов.

Ваша компания должна предоставить руководство по стилю, которое намного меньше, но выполняет необходимую работу.

Форматирование документов — это не совсем стиль, как я использую слова. И это была бы одна из функций редактирования в самом низу списка и далеко за пределами реальных усилий по написанию.

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

Реальная проблема больше похожа на уровни редактирования. И чем занимаются редакторы этих уровней (или вы).

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

Если стиль действительно является проблемой, то у них должен быть отдел редактирования, который преобразует инженерные отчеты в некий «стандарт».

Редактирование строк, редактирование копий, проверки SPAG и низкоуровневые вещи тоже не являются стилем, но также важны.

Попытка навязать инженерам какое-то CMOS-руководство было бы разрушительным и контрпродуктивным.

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

Если вас беспокоит что-то другое, пожалуйста, задайте другой, более прямой вопрос о проблеме, указав, в чем именно заключается ваша проблема с отчетами.