Руководство по стилю документации

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

Что такое стайлгайд?

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

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

В англоязычном сегменте интернета легко найти стайлгайды разных компаний: например, Google, Mailchimp, Veeam. Они буквально-таки всеобъемлющие. Но годятся только для английского языка. А как быть с русским?

Как таковых «стайлгайдов» для великого и могучего нет. Но есть ГОСТы, из которых можно почерпнуть информацию о структуре и содержании тех или иных технических документов; есть “Справочник издателя и автора”, который дает наиболее полную информацию о правилах оформления документов; наконец, есть справочник Д. Э. Розенталя с правилами правописания.

Все они являются фундаментальными источниками, однако было бы слишком трудозатратно каждый раз лазить в них и искать очередной ответ на вопрос «как правильно?» Так что проще один раз сильно напрячься и составить свой стайлгайд, который будет опираться на эти источники и содержать наши локальные правила.

Стайлгайд: начало

Мы разделили стайлгайд на три основных части. Или на три документа:

• стайлгайд документации в вики-системе;
• стайлгайд составления схем;
• стайлгайд документации для клиентов.

Различия правил документации в вики-системе и документации, которая передаётся клиентам, обусловлены по большей части, используемым инструментарием. У нас вики-система Confluence, и у клиентов нет к ней доступа. Им мы передаем документацию в формате офисных документов или переносим в их базу знаний. По этой причине и существуют определенные различия в структуре и оформлении документов.

Вначале мы выделили основные вопросы, которые возникают у технического писателя при создании документации:
— Как мы пишем те или иные термины? Например, мы пишем «кубернетес» или «Kubernetes»? Или «k8s»?
Ответ на такой вопрос должен давать глоссарий. И значит он нам нужен.

— В каком порядке располагаем статьи и как заполняем шаблоны? Какой структуры придерживаемся?
Нужны правила структуры по пространствам, разделам, подразделам и статьям.

— Как мы пишем? Подробно или кратко? Какой стиль написания используем?
Нужно сформулировать хотя бы несколько основных правил.

— А каким языком? Например, насколько допустимо использование профессионализмов, сокращений, канцеляризмов и т.п?
Нужны конкретные правила их использования в документации. А также любые другие правила по написанию, которые помогут привести документацию к единому виду.

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

— Как привести схемы к единому виду? Какие есть общие правила при их составлении? Что нужно отобразить на схеме, какие отношения и связи? Какие типы схем мы составляем?
Нужно сделать унификацию элементов схемы, записать правила использования цветов, шрифтов и размеров, составить библиотеки используемых элементов и привести примеры правильных схем, в которых наиболее полно используются элементы и показаны связи между ними.

В глоссарий мы записали самые распространенные термины, с которыми возникала путаница, и оформили его в виде таблицы:

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

Основной стайлгайд включает в себя следующие разделы:

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

Целевая аудитория — это краткий портрет пользователей, для которых пишется документация. Он позволяет правильно сформулировать правила написания и язык статей.

Раздел с оформлением статей включает в себя такие правила, как:

• обязательное использование макроса оглавления;
• использование заголовков: определили, что для структуры наших статей будет достаточно заголовков 2-го и 3-го уровней — использование заголовков ниже третьего уровня будет только усложнять структуру;
• использование для кода и файлов конфигурации макроса — «блок кода»;
• использование макросов выделения. Например, в каких случаях использовать макрос «информация», а в каких «предупреждение»;
• использование макроса «раскрыть» для длинных списков. Особенность нашей документации в том, что там часто используются списки и они могут существенно удлинять статью. Поэтому если в списке более 10 пунктов, то такой список желательно сделать раскрывающимся;
• использование макроса drawio для схем. Так как схемы требуется постоянно обновлять, то удобнее, когда в документации они располагаются не в виде картинки, а внутри макроса. Это позволяет быстро и просто вносить в схему нужные изменения;
• использование дефисов и тире, жирного и курсива;
• подписи к картинкам и скриншотам — в каких случаях они нужны, а когда их можно опускать;
• использование маркированных и нумерованных списков — в чем разница, когда и какой нужно использовать. Также правила их оформления — пункты маркированных списков начинаются с маленькой буквы и заканчиваются точкой с запятой, пункты нумерованных списков начинаются с заглавной буквы и заканчиваются точкой;
• использование макросов для добавления ссылок и таблиц.

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

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

Например, мы определили четыре основных возможных варианта структуры клиентского проекта:

• простой;
• стандартный;
• расширенный 1;
• расширенный 2.

Для наглядного представления структуры была составлена майндмапа, в которой расписан каждый из 4-х вариантов структуры:

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

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

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

В последнем разделе основного стайлгайда — язык статей. Мы указали все основные правила, которых нужно придерживаться при написании статей документации:

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

Правила оформления схем мы вынесли в отдельный стайлгайд:

Введение описывает, какие типы схем мы составляем и для чего применяется этот стайлгайд.

В общих правилах оформления мы указали:

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

В правилах оформления элементов облачных сервисов описано:

• использование иконок, соответствующих сервису, из готовых библиотек облаков;
• сохранение пропорций и стандартных цветов иконок.

Также мы добавили примеры для схем облачных сервисов.

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

Правила оформления для документации, которая передается клиентам, мы также оформили в отдельный документ со следующим содержанием:

Разделы Введение и Язык написания полностью дублируют основной стайлгайд — здесь правила едины как для статей в вики-системе, так и для офисных документов. Эти разделы скопированы сюда только для удобства — чтобы все правила для определенных документов были в одном месте.

В одноименном разделе мы определили основные типы документов, которые мы передаем нашим клиентам на текущий момент:

• приёмо-сдаточная документация;
• отчет по нагрузочному тестированию;
• отчет по аудиту Kubernetes.

В разделе оформление документов мы подробно описали следующие правила:

• какие мы используем шрифты;
• размеры основного текста и заголовков;
• используемую цветовую гамму;
• размеры полей, используемое выравнивание;
• отступы и междустрочные интервалы;
• использование нумерации, рисунков и подписей к ним;
• использование таблиц и подписей к ним;
• обязательное содержание документов — титульный лист, оглавление, основная часть, заключение;
• использование дефисов и тире;
• использование маркированных и нумерованных списков;
• использование логотипа ITSumma.

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

Какие проблемы решило наличие стайлгайда

Попробую теперь сформулировать, какие именно проблемы мы решили при помощи стайлгайда:

1. Приведение документации к единому виду. Это помогает быстрее и проще ориентироваться по документации.
2. Сокращение времени на адаптацию нового сотрудника в отделе документирования. Теперь не нужно передавать знания из уст в уста, всё хранится в одном месте.
3. Сокращение времени на подготовку документов для клиентов. То есть ускорение оказания услуг нашим заказчикам.
4. Формализация знаний, которые ранее хранились в головах разных людей.

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

Какие вопросы остаются

Самый основной вопрос и сложность — как привести всю документацию в соответствие со стайлгайдом и как это соответствие поддерживать…

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

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

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

Что дальше?

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

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

From Wikipedia, the free encyclopedia

A style guide, or style manual, is a set of standards for the writing and design of documents, either for general use or for a specific publication, organization or field. The implementation of a style guide provides uniformity in style and formatting within a document and across multiple documents. A set of standards for a specific organization is often known as «house style». Style guides are common for general and specialized use, for the general reading and writing audience, and for students and scholars of various academic disciplines, medicine, journalism, the law, government, business, and industry.

International[edit]

Several basic style guides for technical and scientific communication have been defined by international standards organizations. These are often used as elements of and refined in more specialized style guides that are specific to a subject, region, or organization. Some examples are:

Australia[edit]

General[edit]

• Australian Government Style Manual by Digital Transformation Agency. 7th ed.
• Style Manual: For Authors, Editors and Printers by Snooks & Co for the Department of Finance and Administration. 6th ed. ISBN 0-7016-3648-3.
• The Australian Handbook for Writers and Editors by Margaret McKenzie. 4th ed. ISBN 9781921606496.
• The Cambridge Guide to Australian English Usage by Pam Peters of Macquarie University. 2nd ed. ISBN 9780521702423.
• The Complete Guide to English Usage for Australian Students by Margaret Ramsay. 6th ed. ISBN 9780521702423.

Law[edit]

• Australian Guide to Legal Citation published by University of Melbourne Law School. 4th ed. ISBN 9780521702423.

Science[edit]

• Australian manual of scientific style (AMOSS) by Biotext; illustrated by Biotext. 1st ed. ISBN 978-0-9946369-0-4

Canada[edit]

• The Canadian Style: A Guide to Writing and Editing: by Dundurn Press in co-operation with Public Works and the Government Services Canada Translation Bureau. ISBN 1-55002-276-8.

Newspapers[edit]

• CP Stylebook: Guide to newspaper style in Canada maintained by the Canadian Press. ISBN 0-920009-38-7.
• The Globe and Mail Style Book: Originally created to help writers and editors at the Globe and Mail present clear, accurate and concise stories. ISBN 0-7710-5685-0

European Union[edit]

• Interinstitutional Style Guide.^[2]
• English Style Guide («A handbook for authors and translators in the European Commission» – executive branch of the European Union.)^[3]

United Kingdom[edit]

General[edit]

• Copy-editing: The Cambridge Handbook for Editors, Authors and Publishers Judith Butcher. 3rd ed. 1992 Cambridge: Cambridge University Press ISBN 0-521-40074-0
• Fowler’s Modern English Usage. Ed. R. W. Burchfield. Rev. 3rd ed. London: Clarendon Press, 2004. ISBN 0-19-861021-1 (hardcover). Based on Modern English Usage, by Henry Watson Fowler.
• The King’s English, by Henry Watson Fowler and Francis George Fowler.
• The Oxford Style Manual (2003 ed.). Combines The Oxford Guide to Style and The Oxford Dictionary for Writers and Editors, which concentrates on common problems.
• The Complete Plain Words, by Sir Ernest Gowers.
• Usage and Abusage, by Eric Partridge.

For legal documents[edit]

• Oxford Standard for Citation of Legal Authorities (OSCOLA), by the University of Oxford Faculty of Law

For journalism[edit]

• The BBC News Style Guide: by the British Broadcasting Corporation.^[4]
• The Economist Style Guide: by The Economist.^[5]
• The Guardian Style Guide: by The Guardian^[6]
• The Times Style and Usage Guide, by The Times.

For the computer industry (software and hardware)[edit]

• Acorn Technical Publications Style Guide, by Acorn Computers. Provides editorial guidelines for text in RISC OS instructional publications, technical documentation, and reference information.^[7]
• RISC OS Style Guide^[8] by RISC OS Open Limited. Provides design guidelines, help and dialogue box phrasing examples for the software user interface.

United States[edit]

In the United States, both corporate and journalistic forms of mass communication rely on styles provided in the Associated Press Stylebook (AP).^[9] A classic grammar style guide, which is designed to complement the AP Stylebook, is The Elements of Style. Together, these two books are referenced more than any other general style book for U.S. third-person writing used across most professions.^{[citation needed]}

For general writing[edit]

• The Careful Writer, by Theodore Bernstein.
• Bryson’s Dictionary of Troublesome Words: A Writer’s Guide to Getting It Right, by Bill Bryson.
• Garner’s Modern American Usage by Bryan A. Garner.
• The Associated Press Stylebook Basic Books ISBN 978-0-917360-63-3.
• The Elements of Style. By William Strunk, Jr. and E. B. White. (Often referred to as «Strunk and White».)

For legal documents[edit]

• The Bluebook: A Uniform System of Citation. Jointly, by the Harvard Law Review, Yale Law Journal, Columbia Law Review, and Penn Law Review.
• The Indigo Book: An Open and Compatible Implementation of A Uniform System of Citation. Collaboratively by Professor Christopher Jon Sprigman and NYU law students, and published by Public.Resource.Org.
• ALWD Guide to Legal Citation, formerly ALWD Citation Manual, by the Association of Legal Writing Directors
• New York Style Manual: The Tanbook, by the New York State Reporter

For academic papers[edit]

• The Chicago Manual of Style, Chicago: University of Chicago Press.
• A Manual for Writers of Research Papers, Theses, and Dissertations, Chicago Style for Students and Researchers, by Kate L. Turabian. Often referred to as «Turabian.»
• MLA Handbook for Writers of Research Papers, by Joseph Gibaldi. Often referred to as «MLA».
• Publication Manual of the American Psychological Association, by the American Psychological Association (APA).

For journalism[edit]

• The Associated Press Stylebook Basic Books ISBN 978-0-917360-63-3.
• The New York Times Manual of Style and Usage. By Allan M. Siegal and William G. Connolly.
• The Wall Street Journal Guide to Business Style and Usage, by Ronald J. Alsop and the Staff of the Wall Street Journal.
• The BuzzFeed Style Guide: by Emmy Favilla and Megan Paolone.^[10]

For electronic publishing[edit]

• The Columbia Guide to Online Style, by Janice Walker and Todd Taylor.
• Web Style Guide: Basic Design Principles for Creating Web Sites, by Patrick J. Lynch and Sarah Horton.
• The Associated Press Stylebook, By the Associated Press, Basic Books ISBN 978-0-917360-63-3.

For business[edit]

• The Associated Press Stylebook Basic Books ISBN 978-0-917360-63-3.
• The Business Style Handbook, An A-to-Z Guide for Effective Writing on the Job, by Helen Cunningham and Brenda Greene.^[11]
• The Gregg Reference Manual, by William A. Sabin.

For the computer industry (software and hardware)[edit]

• Apple Style Guide, published online by Apple Inc.^[12] Provides editorial guidelines for text in Apple instructional publications, technical documentation, reference information, training programs, and the software user interface.
  An earlier version was the Apple Publications Style Guide.^[13][14]
• DigitalOcean documentation style guide, published online by DigitalOcean.^[15]
• GNOME documentation style guide, published online by GNOME.^[16]
• Google Developer Documentation Style Guide, published online by Google.^[17] Provides a set of editorial guidelines for anyone writing developer documentation for Google-related projects.
• Mailchimp content style guide, published online by Mailchimp.^[18]
• Microsoft Writing Style Guide, published online by Microsoft Corporation.^[19] Provides a style standard for technical documentation including use of terminology, conventions, procedure, design treatments, and punctuation and grammar usage. Before 2018, Microsoft published a book, the Microsoft Manual of Style for Technical Publications.
• MongoDB documentation style guide, published by MongoDB.^[20]
• Mozilla Writing Style Guide, published online by Mozilla.^[21]
• Rackspace style guide for technical content, published online by Rackspace.^[22]
• Read Me First! A Style Guide for the Computer Industry, by Sun Technical Publications, 3rd ed., 2010.^[23]
• Red Hat style guide for technical documentation, published online by Red Hat.^[24]
• Salesforce style guide for documentation and user interface text, published online by Salesforce.^[25]
• SUSE documentation style guide, published online by SUSE.^[26]
• The IBM Style Guide: Conventions for Writers and Editors, 2011,^[27] and Developing Quality Technical Information: A Handbook for Writers and Editors, 2014,^[28] from IBM Press.
• The Splunk Style Guide, published online by Splunk.^[29] Provides a writing style reference for anyone writing or editing technical documentation.
• The Yahoo! Style Guide, 2010.^[30]

Editorial style guides on preparing a manuscript for publication[edit]

• The Associated Press Stylebook Basic Books ISBN 978-0-917360-63-3.
• The Chicago Manual of Style, by University of Chicago Press staff.
• Words into Type, by Marjorie E. Skillin, Roberta

Academic[edit]

• The Chicago Manual of Style. The standard of the academic publishing industry including many journal publications.
• A Manual for Writers of Term Papers, Theses, and Dissertations (frequently called «Turabian style»)—Published by Kate L. Turabian, the graduate school dissertation secretary at the University of Chicago from 1930 to 1958. The school required her approval for every master’s thesis and doctoral dissertation. Her stylistic rules closely follow The Chicago Manual of Style, although there are some differences.
• ACS Style Guide—for scientific papers published in journals of the American Chemical Society.
• American Medical Association Manual of Style—for medical papers published in journals of the American Medical Association.
• American Psychological Association Style Guide—for the behavioral and social sciences; published by the American Psychological Association.
• American Sociological Association Style Guide—for the social sciences; published by the American Sociological Association.
• Geoscience Reporting Guidelines—for geoscience reports in industry, academia and other disciplines.^[31]
• Handbook of Technical Writing, by Gerald J. Alred, Charles T. Brusaw, and Walter E. Oliu.—for general technical writing.
• IEEE style—used in many technical research papers, especially those relating to computer science.
• The Little Style Guide by Leonard G. Goss and Carolyn Stanford Goss—provides a distinctively religious examination of style and language for writers and editors in religion, philosophy of religion, and theology—ISBN 978-0-8054-2787-5.
• MHRA Style Guide—for the arts and humanities; published by the Modern Humanities Research Association. Available as a free download (see article).
• MLA Style Manual, and the MLA Handbook for Writers of Research Papers—for subjects in the arts and the humanities; published by the Modern Language Association of America (MLA).
• SBL Handbook of Style—Society of Biblical Literature style manual specifically for the field of ancient Near Eastern, biblical, and early Christian studies. The SBL Handbook of Style includes a recommended standard format for abbreviation of Primary Sources in Ancient Near Eastern, biblical, and early Christian Studies.
• Scientific Style and Format: The CSE Manual for Authors, Editors, and Publishers—for scientific papers published by the Council of Science Editors (CSE), a group formerly known as the Council of Biology Editors (CBE).^[32]
• The Style Manual for Political Science—used by many American political science journals; published by the American Political Science Association.

Communities[edit]

• GLAAD Media Reference Guide, 8th ed., GLAAD College Media Reference Guide, 1st ed., GLAAD Chinese Media Reference Guide, 1st ed. — published by GLAAD to encourage media outlets to use language and practices inclusive of LGBT people. Available as a free download.^[33]

Art[edit]

• Association of Art Editors Style Guide^[34]

See also[edit]

References[edit]

External links[edit]

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

Что входит в стайл гайд?

• Цветовая палитра.
• Типографика.
• Текстовые блоки с заголовками и без заголовков.
• Инпуты (поля для ввода данных).
• Компоненты.
• Сетка макета.
• Модальные окна.
• Описание анимации.

Цветовая палитра

Для каждого проекта цветовая палитра создается индивидуально, и состоит из 10 основных цветов; бывают ещё нейтральные (например, для фона плашек) и вспомогательные. Ключевые цвета используются во всех макетах проекта. Иногда, когда проект большой и цветов много, для удобства создаются группы цветов с общим названием по назначению.

Типографика и текстовые блоки

В хорошей типографике все читаемо и все “на своих местах”. От выбора шрифта зависит удобство чтения и то, насколько пользователь задержится на сайте. В типографике необходимо продумывать шрифтовые пары и описывать правила применения тех или иных заголовков, а также отображать их вес в соотношении друг к другу.

Инпуты

Нужно максимально полно отображать все состояния полей для ввода и выпадающих списков. Это поможет пользователю во взаимодействии с сайтом и упростит ему поиски нужной информации.

Компоненты

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

Сетка макета

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

Модальные окна

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

Описание анимации

Анимация описывается в комментариях к макету страницы или же прилагается отдельный документ с примерами взаимодействий для того или иного блока элемента текста слайдера.

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

Международный

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

Австралия

Общий

• Руководство по стилю правительства Австралии от Агентства цифровой трансформации . 7-е изд.
• Руководство по стилю: для авторов, редакторов и печатников от Snooks & Co для Департамента финансов и администрации . 6-е изд.
  ISBN  0-7016-3648-3 .
• Австралийский справочник для писателей и редакторов Маргарет Маккензи. 4-е изд. ISBN  9781921606496 .
• Кембриджское руководство по использованию австралийского английского языка Пэм Питерс из Университета Маккуори . 2-е изд. ISBN  9780521702423 .
• Полное руководство по использованию английского языка для австралийских студентов Маргарет Рамзи. 6-е изд. ISBN  9780521702423 .

Закон

• Австралийское руководство по юридическому цитированию, опубликованное юридической школой Мельбурнского университета. 4-е изд. ISBN  9780521702423 .

Наука

• Австралийское руководство научного стиля (AMOSS) от Biotext; проиллюстрировано Биотекстом. 1-е изд. ISBN  978-0-9946369-0-4

Канада

• Канадский стиль: руководство по написанию и редактированию : издано Dundurn Press в сотрудничестве с Public Works и Бюро переводов государственных служб Канады. ISBN  1-55002-276-8 .

Газеты

• CP Stylebook : Руководство по газетному стилю в Канаде, поддерживаемое Canadian Press . ISBN  0-920009-38-7 .
• Книга стилей Globe and Mail : изначально создавалась, чтобы помочь писателям и редакторам Globe and Mail представлять ясные, точные и сжатые истории. ISBN  0-7710-5685-0

Европейский Союз

• Руководство по межведомственному стилю .
• English Style Guide («Справочник для авторов и переводчиков Европейской Комиссии » — исполнительная власть Европейского Союза .)

Великобритания

Общий

• Копирование-редактирование: Кембриджский справочник для редакторов, авторов и издателей Джудит Бутчер. 3-е изд. 1992 Кембридж: Издательство Кембриджского университета ISBN  0-521-40074-0
• Современное английское использование Фаулера . Эд. Р. У. Берчфилд. Ред. 3-е изд. Лондон: Clarendon Press , 2004. ISBN  0-19-861021-1 (твердый переплет). Основано на современном английском языке Генри Ватсона Фаулера .
• «Королевский английский » Генри Ватсона Фаулера и Фрэнсиса Джорджа Фаулера .
• Руководство по оксфордскому стилю (издание 2003 г.). Объединяет Оксфордское руководство по стилю и Оксфордский словарь для писателей и редакторов , в котором основное внимание уделяется общим проблемам.
• Полное членораздельно , по сэр Эрнест Гауэрс .
• Использование и злоупотребление , Эрик Партридж .

Для юридических документов

• Оксфордский стандарт цитирования юридических властей ( OSCOLA ),Юридический факультет Оксфордского университета

Для журналистики

• Руководство по стилю BBC News : Британской радиовещательной корпорацией .
• Руководство по стилю Economist : The Economist .
• Руководство по стилю новостей The Fourth Estate : от компании Fourth Estate Public Benefit Corporation
• Руководство по стилю Guardian : от The Guardian
• Руководство по стилю и использованию Times от The Times .

Для компьютерной индустрии (программное и аппаратное обеспечение)

• Руководство по стилю технических публикаций Acorn , Acorn Computers . Содержит редакционные рекомендации для текста в учебных публикациях, технической документации и справочной информации по ОС RISC .
• Руководство по стилю ОС RISC от RISC OS Open Limited . Предоставляет рекомендации по дизайну, справку и примеры формулировок диалоговых окон для пользовательского интерфейса программного обеспечения.

Соединенные Штаты

В Соединенных Штатах как корпоративные, так и журналистские формы массовой коммуникации опираются на стили, представленные в сборнике стилей Associated Press (AP). Классическое руководство по стилю грамматики, разработанное как дополнение к книге стилей AP, — это Элементы стиля . Вместе на эти две книги ссылаются больше, чем на любую другую книгу по общему стилю письма от третьего лица в США, используемую в большинстве профессий.

Для общего письма

• «Осторожный писатель » Теодора Бернштейна .
• Брайсон Словарь по хлопотно слов: Руководство Автора к Getting It Right , по Билл Брайсон .
• Современный американский Использование Гарнера по Bryan A. Garner .
• Классика стиля — представляет собой письменное руководство Уильяма Странка-младшего , Эмерсона , Уитмена , По и других писателей.
• ISBN 978-0-917360-63-3 книги стилей Associated Press . 
• Элементы стиля . По Уильям Strunk, младший и EB White . (Часто упоминается как «Странк и Белый».)

Для юридических документов

• Синяя книга: единая система цитирования . Совместно издано Harvard Law Review , Yale Law Journal , Columbia Law Review и Penn Law Review .
• ALWD Руководство по правовым Citation , ранее ALWD Цитирование Руководство, по ассоциации юридических документов директоров
• Руководство по стилю Нью-Йорка : The Tanbook, газета New York State Reporter

Для научных работ

• Чикагское руководство стиля , Чикаго: University of Chicago Press.
• Пособие для авторов исследовательских работ, тезисов и диссертаций в чикагском стиле для студентов и исследователей , написанное Кейт Л. Турабиан . Часто упоминается как « Турабский ».
• Справочник MLA для авторов исследовательских работ , Джозеф Гибальди . Часто упоминается как «MLA».
• Публикация Руководство Американской психологической ассоциации , по Американской психологической ассоциации (APA).

Для журналистики

• ISBN 978-0-917360-63-3 книги стилей Associated Press . 
• Руководство по стилю новостей The Fourth Estate : от компании Fourth Estate Public Benefit Corporation
• Руководство по стилю и использованию New York Times . Аллан М. Сигал и Уильям Г. Коннолли.
• Руководство Wall Street Journal по деловому стилю и использованию , Рональд Дж. Олсоп и сотрудники Wall Street Journal .
• Руководство по стилю BuzzFeed : Эмми Фавилла и Меган Паолоне.

Для электронных публикаций

• Колумбийский путеводитель по онлайн-стилю , Дженис Уокер и Тодд Тейлор.
• Руководство по веб-стилю: основные принципы дизайна для создания веб-сайтов , Патрик Дж. Линч и Сара Хортон .
• Книга стилей Ассошиэйтед Пресс , Ассошиэйтед Пресс, ISBN основных книг 978-0-917360-63-3 . 

Для бизнеса

• ISBN 978-0-917360-63-3 книги стилей Associated Press . 
• Руководство по деловому стилю, Руководство от А до Я по эффективному письму на работе , Хелен Каннингем и Бренда Грин.
• Справочное руководство Грегга , Уильям А. Сабин.

Для компьютерной индустрии (программное и аппаратное обеспечение)

• Руководство по стилю Apple , опубликованное в Интернете компанией Apple Inc. Содержит редакционные правила для текста в учебных публикациях Apple, технической документации, справочной информации, обучающих программ и пользовательского интерфейса программного обеспечения.
  Более ранней версией было Руководство по стилю публикаций Apple.
• Руководство по стилю документации DigitalOcean, опубликованное в Интернете компанией DigitalOcean .
• Руководство по стилю документации GNOME, опубликованное в сети GNOME .
• Руководство по стилю документации для разработчиков Google, опубликованное в Интернете компанией Google . Предоставляет набор редакционных правил для всех, кто пишет документацию для разработчиков по проектам, связанным с Google.
• Руководство по стилю контента Mailchimp, опубликованное в сети Mailchimp .
• Руководство по стилю письма Microsoft , опубликованное в Интернете корпорацией Microsoft . Предоставляет стандарт стиля для технической документации, включая использование терминологии, условных обозначений, процедур, методов проектирования, а также использования знаков препинания и грамматики. До 2018 года Microsoft опубликовала книгу Microsoft Manual of Style for Technical Publications .
• Руководство по стилю документации MongoDB, опубликованное MongoDB .
• Руководство по стилю написания Mozilla, опубликованное в Интернете компанией Mozilla .
• Руководство по стилю Rackspace для технического контента, опубликованное в Интернете компанией Rackspace .
• Прочтите меня в первую очередь! Руководство по стилю для компьютерной индустрии , Sun Technical Publications, 3-е изд., 2010 г.
• Руководство по стилю Red Hat для технической документации, опубликованное в сети Red Hat .
• Руководство по стилю Salesforce для документации и текста пользовательского интерфейса, опубликованное в сети Salesforce .
• Руководство по стилю документации SUSE, опубликованное SUSE в Интернете .
• Руководство по стилю IBM: соглашения для писателей и редакторов , 2011 г., и « Разработка качественной технической информации: справочник для писателей и редакторов» , 2014 г., издано IBM Press .
• Руководство по стилю Splunk , опубликованное на сайте Splunk . Предоставляет справочник по стилю письма для всех, кто пишет или редактирует техническую документацию.
• Yahoo! Гид по стилю , 2010.

Руководства по редакционному стилю подготовки рукописи к публикации

• ISBN 978-0-917360-63-3 книги стилей Associated Press . 
• Чикагское руководство по стилю , составленное сотрудниками Чикагского университета .
• Слова в шрифт, Марджори Э. Скиллин, Роберта

Академический

• Чикагское руководство стиля . Стандарт академической издательской индустрии, включая многие журнальные публикации.
• Пособие для писателей курсовых , тезисов и диссертаций (часто называемое « турабским стилем») — опубликовано Кейт Л. Турабиан , секретарем диссертаций в аспирантуре Чикагского университета с 1930 по 1958 год. Школа требовала ее одобрения для каждого кандидатская и докторская диссертации. Ее стилистические правила полностью соответствуют Чикагскому руководству по стилю , хотя есть некоторые отличия.
• ACS Руководство по стилю -для научных статей , опубликованных в журналах о Американском химическом обществе .
• Руководство по стилю Американской медицинской ассоциации — для медицинских статей, опубликованных в журналах Американской медицинской ассоциации .
• Руководство по стилю Американской психологической ассоциации — для поведенческих и социальных наук; опубликовано Американской психологической ассоциацией .
• Руководство по стилю Американской социологической ассоциации — для социальных наук; опубликовано Американской социологической ассоциацией .
• Рекомендации по составлениюотчетов по геонаукам — для отчетов по геонаукам в промышленности, академических кругах и других дисциплинах.
• Справочник по техническому письму , составленный Джеральдом Дж. Алредом, Чарльзом Т. Брусо и Уолтером Э. Олиу — для общего технического письма.
• Стиль IEEE — используется во многих технических исследованиях, особенно в тех, которые касаются информатики .
• «Маленькое руководство по стилю » Леонарда Г. Госса и Кэролайн Стэнфорд Госс — содержит отчетливо религиозную экспертизу стиля и языка для писателей и редакторов религии, философии религии и теологии — ISBN  978-0-8054-2787-5 .
• Руководство по стилю MHRA — для искусства и гуманитарных наук ; опубликовано Ассоциацией современных гуманитарных исследований . Доступно для бесплатной загрузки (см. Статью).
• MLA стиль руководства , и ГНД Руководство для писателей научно — исследовательских работ -для субъектов в области искусства и гуманитарных наук ; опубликовано Американской ассоциацией современного языка (MLA).
• SBL Handbook of Style — Руководство по стилю Общества библейской литературы, специально предназначенное для изучения древнего Ближнего Востока, библейских и раннехристианских исследований. SBL Справочник стиля включаетсебя рекомендуемый стандартный формат для сокращения источников первичных в Древнем ближневосточных, библейском и ранних христианских исследованиях.
• Научный стиль и формат: Руководство CSE для авторов, редакторов и издателей — для научных статей, опубликованных Советом научных редакторов (CSE), группой, ранее известной как Совет редакторов биологии (CBE).
• Руководство по стилям для политологии — используется многими американскими журналами по политологии ; опубликовано Американской ассоциацией политологии .

Сообщества

• Справочное руководство по СМИ GLAAD , 8-е изд., Справочное руководство по СМИ колледжа GLAAD , 1-е изд., Справочное руководство по китайским СМИ GLAAD , 1-е изд. — опубликовано GLAAD, чтобы побудить средства массовой информации использовать язык и практику с участием ЛГБТ. Доступно для бесплатной загрузки.

Изобразительное искусство

• Руководство по стилю Ассоциации художественных редакторов

Смотрите также

Рекомендации

Внешние ссылки

Представьте, что ваша компания планирует расширяться на зарубежные рынки. Вам нужно перевести массу документации, маркетинговых материалов и сайт. Завести блог для продвижения тоже было бы неплохо. Эти задачи вы поручаете нескольким надежным профессионалам, но в последний момент решаете всё проверить у независимого специалиста. И вдруг выясняется, что тексты, формально соответствуя оригиналу, вызывают тем не менее совсем иные эмоции и ассоциации. А еще — что переводы разных текстов противоречат друг другу: в каталогах цены указаны в местной валюте, а на сайте — в долларах; в печатных буклетах название вашей компании переведено, а в онлайн-магазине, которым занимались другие подрядчики, осталось на языке оригинала. В результате на исправление всего этого уходит масса времени и денег.

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

Впрочем, задача сохранить единый стиль и согласованность переводов не нова. И решение давно найдено: стайлгайд (от англ. style guide), или руководство по стилю.

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

Что такое руководство по стилю?

Стайлгайд — это документ, где собраны пожелания заказчика относительно стиля (что понятно из названия), тона изложения, особенностей оформления и другие вопросы, для которых в целевом языке перевода нет строгих правил. Какой должна быть интонация: сдержанно формальной или непринужденно разговорной? Можно ли использовать сленг? Что делать с ценами? Придерживаться метрической или имперской системы мер? Важно ли везде одинаково оформлять даты? Переводить ли названия организаций и инициатив?

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

Какие преимущества дает стайлгайд?

Руководство по стилю поможет добиться:

• профессионального оформления текстов;
• формирования узнаваемого голоса бренда на новом рынке;
• более быстрого перевода без потери качества.

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

Во-вторых, когда вы пишете для своих клиентов, будь то электронные рассылки или бумажные каталоги, вы наверняка выдерживаете общий стиль, тон обращения. Он может быть дружественным, даже почти фамильярным, а может — торжественным и в высшей степени уважительным. Вы можете допускать вольности и шутки или писать только строго по делу. Всё это и есть голос вашего бренда. Он позволяет читателям подсознательно отличать вас от конкурентов. Поэтому очень важно выдерживать единый стиль в переводных текстах. Здесь тоже поможет стайлгайд.

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

Заказать обратный звонок

В каких случаях необходим стайлгайд?

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

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

Стайлгайд необходим и тогда, когда вам предстоит работа над крупным или долговременным проектом. Локализация большого каталога или всего вашего сайта требует структурированных письменных инструкций.

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

Что стоит включить в руководство по стилю?

Объем стайлгайда может быть разным. У компаний с большим опытом перевода он больше: например, в руководстве у Facebook 30 с лишним страниц, а у другого IT-гиганта — более сотни. Если же компания только начинает работать с новыми рынками, достаточно самой важной информации на 6–8 страницах. Краткое руководство проще освоить тем, кто будет участвовать в локализации. Позже вы сможете добавить то, что окажется важным в ходе работы.

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

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

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

Если вы переводите документы разных жанров или создаете линейки продукции, ориентированные на разных людей, возможно, вы захотите, чтобы они звучали по-разному. Например, если вы хотите, чтобы маркетинговые материалы были покреативнее, а юридические — строгими и сухими; в описаниях продуктов для детей к читателю обращались на «ты», а для пожилых людей — на «вы» или даже «Вы», обо всем этом тоже стоит упомянуть в первой части стайлгайда.

В техническую часть включают рекомендации по формальным вопросам.

• Пунктуация. Как минимум — форма тире и кавычек, с ними вечные вопросы в большинстве языков. Хотя медиа-портал Buzzfeed, например, учитывает даже такие детали, как порядок знаков в довольно редком сочетании «?!».
• Региональные стандарты. Это в первую очередь оформление времени и дат, например, указывать сначала месяц или день. Сюда же относятся правила для номеров телефонов и адресов.
• Переводимость. Нужно ли оставлять на языке оригинала, переводить или транскрибировать названия компаний, линеек и моделей продукции, статей и так далее.
• Упоминания интерфейса ваших программ, если они есть в тексте. Оставлять их на языке оригинала, дублировать переводом или, может быть, уточнять этот вопрос для каждого проекта.
• Другие важные детали. Для русского языка, например, полезно указать, хотите ли вы видеть в своих текстах букву ё.

Кто составляет стайлгайд?

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

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

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

Что дальше?

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

Однако не стоит считать стайлгайд истиной, выбитой на камне. Руководства лучше всего работают, если их периодически пересматривать и адаптировать к переменам. При интенсивных переводах это полезно делать каждые полгода или год. Если вы локализуете материалы редко, документ может прожить 3–5 лет.

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

Четкие инструкции и слаженная работа — это высокое качество ваших текстов. А это — в наших общих интересах!

Текст: Полина Скурихина, Анна Марковская