1 files changed, 326 insertions, 0 deletions
diff --git a/documentation/content/ru/books/fdp-primer/writing-style/_index.adoc b/documentation/content/ru/books/fdp-primer/writing-style/_index.adoc
new file mode 100644
index 0000000000..51cc579684
--- /dev/null
+++ b/documentation/content/ru/books/fdp-primer/writing-style/_index.adoc
@@ -0,0 +1,326 @@
+---
+description: 'Стиль написания и некоторые соглашения, используемые в проекте документации FreeBSD'
+next: books/fdp-primer/editor-config
+params:
+  path: /books/fdp-primer/writing-style/
+prev: books/fdp-primer/manual-pages
+showBookMenu: true
+tags: ["writing", "style", "typos", "one sentence per line"]
+title: 'Глава 12. Стиль написания'
+weight: 12
+---
+
+[[writing-style]]
+= Стиль написания
+:doctype: book
+:toc: macro
+:toclevels: 2
+:icons: font
+:sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 12
+:partnums:
+:source-highlighter: rouge
+:experimental:
+:images-path: books/fdp-primer/
+
+ifdef::env-beastie[]
+ifdef::backend-html5[]
+:imagesdir: ../../../../images/{images-path}
+endif::[]
+ifndef::book[]
+include::shared/authors.adoc[]
+include::shared/mirrors.adoc[]
+include::shared/releases.adoc[]
+include::shared/attributes/attributes-{{% lang %}}.adoc[]
+include::shared/{{% lang %}}/teams.adoc[]
+include::shared/{{% lang %}}/mailing-lists.adoc[]
+include::shared/{{% lang %}}/urls.adoc[]
+toc::[]
+endif::[]
+ifdef::backend-pdf,backend-epub3[]
+include::../../../../../shared/asciidoctor.adoc[]
+endif::[]
+endif::[]
+
+ifndef::env-beastie[]
+toc::[]
+include::../../../../../shared/asciidoctor.adoc[]
+endif::[]
+
+[[writing-style-tips]]
+== Советы
+
+Техническая документация может быть улучшена за счёт последовательного применения нескольких принципов. Большинство из них можно разделить на три цели: _быть понятным_, _быть полным_ и _быть кратким_. Эти цели могут противоречить друг другу. Хорошее изложение заключается в нахождении баланса между ними.
+
+[[writing-style-be-clear]]
+=== Будьте понятны
+
+Ясность чрезвычайно важна. Читатель может быть новичком или изучать документ на неродном языке. Стремитесь к простому, понятному тексту, который чётко объясняет концепции.
+
+Избегайте витиеватой или украшенной речи, шуток или разговорных выражений. Пишите как можно проще и яснее. Простой текст легче понять и перевести.
+
+Делайте объяснения как можно короче, проще и понятнее. Избегайте пустых фраз вроде "для того чтобы", которые обычно можно заменить на "чтобы". Не используйте снисходительные слова вроде "по сути". Избегайте латинских терминов, таких как "i.e." или "cf.", которые могут быть непонятны за пределами академических или научных кругов.
+
+Следует писать в формальном стиле. Необходимо избегать прямого обращения к читателю. Например, следует использовать формулировку "скопировать файл в [.filename]#/tmp#", а не "вы можете скопировать файл в [.filename]#/tmp#".
+
+Приводите понятные, корректные и _проверенные_ примеры. Простой пример лучше, чем отсутствие примера. Хороший пример ещё лучше. Не приводите плохих примеров, которые можно распознать по извинениям или фразам вроде «но на самом деле так делать не стоит». Плохие примеры хуже, чем их отсутствие. Приводите хорошие примеры, потому что _даже если предупредить читателя, чтобы он не использовал пример в таком виде_, он всё равно, скорее всего, воспользуется им как есть.
+
+Избегайте _неопределённых выражений_, таких как «должен», «может», «попытаться» или «смог бы». Эти слова создают впечатление, что автор не уверен в фактах, и вызывают сомнения у читателя.
+
+Аналогично, давайте инструкции в виде повелительных команд: не "вам следует сделать это", а просто "сделайте это".
+
+[[writing-style-be-complete]]
+=== Будьте полными
+
+Не делайте предположений о способностях или уровне навыков читателя. Сообщите им то, что им необходимо знать. Давайте ссылки на другие документы, чтобы предоставить справочную информацию без необходимости её повторного изложения. Поставьте себя на место читателя, предугадайте вопросы, которые у него возникнут, и ответьте на них.
+
+[[writing-style-be-concise]]
+=== Будьте краткими
+
+Хотя функции должны быть описаны полностью, иногда информации так много, что читателю сложно найти нужную деталь. Баланс между полнотой и лаконичностью — это непростая задача. Один из подходов — включить введение, затем раздел «быстрый старт» с описанием наиболее распространённого сценария, а после него — подробный справочный раздел.
+
+[[writing-style-guidelines]]
+== Рекомендации
+
+Для обеспечения единообразия среди множества авторов документации FreeBSD были разработаны рекомендации, которым следует придерживаться при написании.
+
+Используйте американское написание английских слов::
+Существует несколько вариантов английского языка с разным написанием одних и тех же слов. Если варианты написания отличаются, используйте американский английский. Например, «color», а не «colour», «rationalize», а не «rationalise», и так далее.
++
+[NOTE]
+====
+Использование британского варианта английского языка может быть допустимо в случае предоставленной статьи, однако орфография должна быть единообразной во всем документе. Остальные документы, такие как книги, веб-сайты, справочные страницы и т. д., должны использовать американский вариант английского языка.
+====
+
+Не используйте сокращения::
+Не используйте сокращения. Всегда пишите фразу полностью. "Don't use contractions" является неправильным вариантом.
++
+Избегание сокращений способствует более формальному тону, повышает точность и немного облегчает работу переводчиков.
+
+Используйте серийную запятую::
+В списке элементов внутри абзаца разделяйте каждый элемент запятой. Последний элемент отделяйте от остальных запятой и словом "and".
++
+Например:
++
+This is a list of one, two and three items (Вот список из одного, двух и трёх элементов).
++
+Это список из трех элементов: "one", "two" и "three" или список из двух элементов: "one" и "two and three"?
++
+Лучше быть точным и включать серийную запятую:
++
+This is a list of one, two, and three items (Вот список из одного, двух и трёх элементов).
+Избегайте избыточных фраз::
+Избегайте избыточных фраз. В частности, "команда", "файл" и "man команда" часто избыточны.
++
+Например, команды:
++
+Неверно: Используйте команду `git` для обновления исходного кода.
++
+Правильно: Используйте `git` для обновления исходников.
++
+Имена файлов:
++
+Неверно: ... в имени файла [.filename]#/etc/rc.local#...
++
+Правильно: ... в [.filename]#/etc/rc.local#...
++
+Ссылки на страницы Справочника (во втором примере используется `man:[]` с сущностью man:csh[1]):
++
+Неправильно: Дополнительную информацию смотрите в `man csh`.
++
+Правильно: См. man:csh[1].
+
+Для получения дополнительной информации о стиле написания текстов см. http://www.bartleby.com/141/[«Элементы стиля»] Уильяма Странка.
+
+[[writing-style-guide]]
+== Руководство по стилю
+
+Чтобы сохранить единообразие исходного кода документации при редактировании множеством разных людей, пожалуйста, следуйте этим стилевым соглашениям.
+
+[[one-sentence-per-line]]
+=== Одно предложение на строку
+
+Используйте семантические разрывы строк в документации, метод, называемый "одно предложение на строку". Идея этого метода заключается в том, чтобы помочь пользователям писать и читать документацию. Для получения дополнительной информации об этом методе прочитайте страницу https://sembr.org/[Semantic Line Breaks].
+
+Это пример, который не использует "одно предложение на строку".
+
+....
+All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.
+....
+
+И вот пример, использующий этот метод.
+
+....
+All human beings are born free and equal in dignity and rights.
+They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.
+....
+
+[[writing-style-acronyms]]
+=== Аббревиатуры
+
+Акроним должен быть определён при первом упоминании в документе, например: «Network Time Protocol (NTP)». После того как акроним определён, используйте только акроним, если контекст не требует полного термина. Обычно акроним определяется один раз в главе или документе.
+
+Все аббревиатуры должны быть заключены в символ `.
+
+[[writing-style-special-characters]]
+== Список специальных символов
+
+Этот список специальных символов показывает правильный синтаксис и результат их использования в документации FreeBSD. Если нужного символа нет в списке, задайте вопрос на {freebsd-doc}.
+
+[.informaltable]
+[cols="1,1,1", frame="none", options="header"]
+|===
+| Имя
+| Синтаксис
+| Выводится
+
+
+| Авторское право (copyright)
+| +(C)+
+| (С)
+
+| Зарегистрировано
+| +(R)+
+| (R)
+
+| Товарный знак
+| +(TM)+
+| (TM)
+
+| Тире
+| +--+
+| --
+
+| Многоточия
+| +...+
+| ...
+
+| Одиночная стрелка вправо
+| +->+
+| ->
+
+| Двойная правая стрелка
+| +=>+
+| =>
+
+| Одиночная стрелка влево
+| +<-+
+| <-
+
+| Двойная левая стрелка
+| +<=+
+| <=
+
+|===
+
+[[writing-style-linting-vale]]
+== Проверка стиля с помощью Vale
+
+Для обеспечения ясности и единообразия во всей документации и на страницах веб-сайта в дерево документации были добавлены стили link:https://vale.sh[Vale]. link:https://vale.sh[Vale] — это мощный линтер для создания пользовательских правил написания текста, который можно использовать в различных сценариях. В настоящее время link:https://vale.sh[Vale] можно применять как инструмент командной строки, в CI/CD-процессах и интегрировать в предпочитаемый редактор.
+
+Следующая таблица описывает текущие названия правил и их соответствующую степень серьёзности.
+
+[.informaltable]
+[cols="1,1", frame="none", options="header"]
+|===
+| Имя
+| Степень серьезности
+
+| FreeBSD.BrandTerms
+| ошибка
+
+| FreeBSD.ConsciousLanguage
+| warning
+
+| FreeBSD.Contractions
+| предложение
+
+| FreeBSD.EOLSpacing
+| warning
+
+| FreeBSD.Hang
+| warning
+
+| FreeBSD.Hyphens
+| warning
+
+| FreeBSD.Spacing
+| ошибка
+
+| FreeBSD.SuperfluousOptArgInLinks
+| предложение
+
+| Vale.Avoid
+| ошибка
+
+| Vale.Repetition
+| ошибка
+
+| Vale.Spelling
+| ошибка
+
+| Vale.Terms
+| ошибка
+
+|===
+
+[[writing-style-linting-vale-rules]]
+=== Текущие правила Vale
+
+. FreeBSD.BrandTerms: В соответствии с правилами авторского права The FreeBSD Foundation, *freebsd* следует писать как *FreeBSD*. Аналогично, у каждого крупного поставщика и компании есть свои правила написания их торговых марок и брендов. Следует проявлять уважение к брендам других и уделять время правильному написанию PostgreSQL, Node.js, Let's Encrypt и т. д. Отсутствующие названия брендов следует добавлять в файл [.filename]#.vale/styles/FreeBSD/BrandTerms.yml# в репозитории `doc`.
+
+. FreeBSD.ConsciousLanguage: Это правило предлагает использовать осознанный язык, чтобы по возможности избегать чувствительных слов, указывающих на цвет кожи, возраст, расу или сексуальную ориентацию людей.
+
+. FreeBSD.Сокращения: Не следует использовать сокращенные слова. Это правило исключает все сокращения и рекомендует использовать полные слова.
+
+. FreeBSD.EOLSpacing: В большинстве документов присутствуют пробелы в конце строк, что не является желательной ситуацией.
+
+. FreeBSD.Hang: Термин `Hang` часто используется для обозначения ситуации, когда приложение перестает отвечать. Это правило предлагает более подходящую формулировку.
+
+. FreeBSD.Дефисы: Часто наречия, оканчивающиеся на 'ly', добавляются с дефисом, что является ошибкой.
+
+. FreeBSD.Расстояние: Часто двойные пробелы трудно заметить невооруженным глазом, и здесь это решается.
+
+. FreeBSD.SuperfluousOptArgInLinks: Рекомендуется оставлять квадратные скобки пустыми в макросах `link:`, если отображаемый текст совпадает с URL.
+
+. Vale.Avoid: Запрещает использование терминов из списка *НЕ ИСПОЛЬЗОВАТЬ* в документации The FreeBSD Project. Если обнаружено слово, которое не должно присутствовать в документации, его следует добавить в файл [.filename]#.vale/styles/Vocab/Terms/reject.txt# в репозитории `doc`. На данный момент список пуст.
+
+. Vale.Repetition: Одни и те же слова часто набираются дважды при отходе от клавиатуры и возвращении к работе. Это правило находит повторяющиеся слова и предупреждает пользователей.
+
+. Vale.Spelling: В настоящее время в документации и на веб-сайте используется смесь написания en_US и en_GB. Vale поставляется со встроенным словарем, который использует строго en_US и не принимает варианты написания en_GB для любых слов.
+
+. Vale.Terms: Обеспечивает соблюдение *ПРЕДПОЧТИТЕЛЬНЫХ* терминов для проекта FreeBSD. В настоящее время список терминов пуст, и специфичные для FreeBSD термины будут добавляться постепенно. Если какое-либо слово считается правильным, но отсутствует в словаре, его следует добавить в файл [.filename]#.vale/styles/Vocab/Terms/accept.txt# в репозитории `doc`.
+
+Дополнительные правила будут введены в будущем по мере необходимости.
+
+[[writing-style-using-vale]]
+=== Использование Vale
+
+link:https://vale.sh[Vale] можно использовать из командной строки, а также из редактора или IDE. Установить package:textproc/vale[] можно следующим образом:
+
+[source, shell]
+....
+$ pkg install vale
+....
+
+[[writing-style-using-vale-commandline]]
+==== Использование Vale в командной строке
+
+Предполагая, что репозиторий `doc` был склонирован в [.filename]#~/doc#, для запуска потребуются следующие команды:
+
+[source, shell]
+....
+% cd ~/doc
+% vale .
+....
+
+[NOTE]
+======
+link:https://vale.sh[Vale] — это программа с высокой нагрузкой на процессор и память из-за специфики приложения, и она может долго не выводить результаты на экран. Лучше запускать её для конкретных папок или файлов, а не для всего репозитория `doc`, так как это уже выполняется в CI-пайплайне.
+======
+
+[[writing-style-using-vale-editors]]
+==== Использование Vale в редакторах
+
+link:https://vale.sh[Vale] работает с основными популярными редакторами, такими как package:editors/vim[], package:editors/emacs[], package:editors/vscode[]. В настоящее время необходимая конфигурация для package:editors/vim[] описана в crossref:editor-config[editor-config-vim, Vim]. Конфигурация для package:editors/emacs[] находится в разработке.