Перейти до змісту

Керівництво по стилю Rocky Linux Documentation

Rocky Linux (RL) — це найшвидше зростаюча корпоративна Linux-система у світі, а її документація також зростає експоненціально завдяки таким учасникам, як ви. Ваш контент вітається в будь-якому форматі, а стилісти документів RL допоможуть вам узгодити його зі стандартами, викладеними тут.

Вступ

Про

Нові внески вітаються, щоб перетворити цю сторінку на найкраще місце в Інтернеті для отримання інформації про використання Rocky Linux. Ви можете створювати документи у форматі, який вам підходить, а команда документації співпрацюватиме з вами або іншим чином допоможе відформатувати їх так, щоб вони виглядали та сприймалися як частина родини Rocky.

У цьому посібнику викладено стандарти стилю англійської мови для покращення читабельності, виділення особливих випадків та покращення роботи з перекладом документації Rocky Linux. Щодо запитань про стиль, які не розглядаються в цьому посібнику, зверніться до наступного:

Зробити внесок

Для повнішого розуміння того, як робити внески, зверніться до наших відповідних посібників:

Рекомендації щодо стилю

Метою документації RL є використання чіткої та узгодженої мови для доступності та сприяння поточним перекладам.

Граматика і пунктуація

Ознаки технічного написання, як зазначено в Чиказькому посібнику зі стилю, включають наступне:

  • Подвійні лапки («стиль Чикаго»), а не одинарні лапки («стиль Оксфорд»).
  • Крапки та коми беруться в лапки “ось так,” а не “ось так”.
  • Тире {shift}+{option}+{-} не має пробілів ні перед, ні після, як це, і є кращим для фраз у дужках.
  • Використовуйте послідовну кому перед «і» в списку з трьох елементів: «Горошок, гірчиця та морква».
  • Заголовки, як правило, мають бути написані з великої літери: перше й останнє слова, а також усі іменники, займенники, дієслова та прислівники пишуться з великої літери. Якщо ваш документ краще працює з великими літерами в стилі речень, можливо, через те, що ви часто посилаєтеся на акроніми, зробіть це узгодженим у всьому документі.
  • Заголовки не потребують крапки чи крапки з комою наприкінці, навіть якщо вони вживаються з великої літери, якщо вони не закінчуються абревіатурою.
  • Маркіровані та пронумеровані списки: уникайте початку з великої літери або кінцевих знаків пунктуації, якщо елемент не є повним реченням.

Використання великої літери в заголовках речень

Люди, які використовують vale та інші мовні лінтери, побачать, що вони пропонують використовувати написання з великої літери в стилі речень. Значна частина документації, створеної в нашому пулі документації, використовує цей стиль написання заголовків з великої літери. Просто пам’ятайте, що який би стиль ви не обрали, дотримуйтесь його послідовності в межах вашого документа.

Голос і тон

  • Проста мова. Описується як менш розмовний стиль. Більшість нашої документації відповідає цьому стандарту.
  • Уникайте метафор і ідіом.
  • Скажіть те, що ви маєте на увазі, якомога меншою кількістю слів.
  • Визначте та уникайте непотрібних технічних термінів. Подумайте, що ваша аудиторія – це переважно люди, які певною мірою знайомі з предметом, але можуть не бути експертами в цьому предметі.
  • Винятки для простої мови:
    • Більш розмовний стиль підходить для документації, адресованої новачкам або початківцям, або для написання вмісту, як-от дописів у блогах.
    • Більш формальний або стислий стиль формулювання підходить для документації, адресованої досвідченим користувачам, або документації API (інтерфейс прикладного програмування).
  • Інклюзивна мова.
  • Використання мови розвивається з часом. Деякі слова еволюціонували, щоб нести негативні конотації, тому документацію слід переписати, щоб використовувати нові слова.
    • Master/slave стає primary/secondary або узгодженим організаційним стандартом.
    • Blacklist/whitelist стає blocklist/allowlist або узгодженим організаційним стандартом.
    • Під час створення документації ви можете подумати про інші відповідні приклади.
  • Говорячи про особу невідомої або небінарної статі, зараз вважається прийнятним використовувати "вони" як займенник однини.
  • Коли ви говорите про свої можливості, формулюйте відповіді як здібності, а не обмеження. Наприклад, якщо вам цікаво, чи є у нас документація щодо запуску Steam на Rocky Linux, відповідь не буде просто «ні». Скоріше, «Здається, це чудове місце для вас, щоб створити щось, щоб додати до нашого дерева!»
  • Уникайте скорочень. Це допомагає з перекладом. Винятком є написання чогось у більш розмовному тоні, як-от публікації в блозі чи вітальні інструкції для нових учасників спільноти.
  • Використовуйте active voice. Active voice є точнішим і прямим і допомагає читачеві швидко зрозуміти ваш зміст.

Інші тлумачення голосу та тону

З моменту створення цього посібника зі стилю було створено кілька додаткових документів про голос і тон, зокрема: - Good Docs – погляд перекладача - Active voice – шлях до простого та зрозумілого спілкування

Форматування

Дати

Якщо можливо, використовуйте назву місяця у форматі {day} {Month} {year}. Однак {Month} {day}, {year} також прийнятний для вирішення проблем із чіткістю чи виглядом. У будь-якому випадку, щоб уникнути плутанини, пишіть назви місяців, а не серію чисел. Наприклад: 24 січня 2023 р., але 24 січня 2023 р. також прийнятно, причому обидва варіанти краще, ніж 1/24/2023 або 24/01/2023.

Одноетапні процедури

Якщо у вас є процедура лише з одним кроком, використовуйте маркер, а не номер. Наприклад:

  • Реалізуйте цю ідею і рухайтеся далі.

Мова графічного інтерфейсу

  • Текстові інструкції щодо інтерфейсу користувача: описуючи команду, яку потрібно ввести в інтерфейс користувача, використовуйте слово «enter», а не «put» або «type». Використовуйте блок коду, щоб написати команду (тобто встановити її зворотними галочками):

Приклад тексту Markdown У полі **повідомлення про фіксацію** введіть update_thisdoc.

  • Назви елементів інтерфейсу користувача: жирним шрифтом назви елементів інтерфейсу, таких як кнопки, пункти меню, назви діалогових вікон тощо, навіть якщо це слово не можна натиснути:

Example Markdown text In the **Format** menu, click **Line Spacing**.

Структура

Початковий вміст кожного посібника або сторінки/розділу книги

  • Анотація. Коротка інформація про те, чого очікувати від цієї сторінки
  • Цілі. Маркірований список того, що ця сторінка передасть читачеві
  • Навички необхідні/вивчені.
  • Рівень складності. 1 зірка для легкого, 2 для середнього тощо.
  • Час читання. Щоб визначити це число, розділіть слова у вашому документі на швидкість читання 75 слів на хвилину.

Попередження

У Markdown попередження — це спосіб помістити інформацію у вікно, щоб виділити її. Вони не є обов'язковими для документування, але можуть бути корисним інструментом. Дізнайтеся більше про застереження з нашого [документа Rocky Formatting] (rockydocs_formatting.md).

Доступність

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

Зображення

  • Надайте текстові описи в тексті заміщення або підписах для кожного нетекстового елемента, наприклад діаграм, зображень або значків.
  • По можливості уникайте скріншотів із текстом.
  • Зробіть альтернативний текст значущим, а не просто описовим. Для значків дій, наприклад, введіть опис функції, а не опис її вигляду.

Посилання

  • Зробіть посилання описовими, щоб було зрозуміло, куди вони ведуть із тексту чи контексту. Уникайте гіперпосилань із назвами на зразок «клацніть тут».
  • Переконайтеся, що всі посилання працюють, як описано.

Таблиці

  • Створюйте таблиці в логічному порядку зліва направо, зверху вниз.
  • Уникайте порожніх клітинок у верхній або лівій частині таблиці.
  • Уникайте об’єднаних клітинок, які охоплюють кілька стовпців.

Кольори

  • Деяким елементам у Markdown, наприклад попередженням, призначено колір, щоб полегшити візуальне розуміння. Загалом, вони також мають присвоєну назву; наприклад, застереження «небезпека» відображає червону рамку, але також містить дескриптор «небезпека», вбудований в опис. Але, створюючи спеціальне попередження, майте на увазі, що колір не може бути єдиним засобом передачі команди або рівня попередження.
  • Будь-яка команда, яка містить сенсорний напрямок, як-от вище або нижче, колір, розмір, візуальне розташування на сторінці тощо, також має включати напрямок, який можна передати лише текстовим описом.
  • Створюючи графічний елемент, переконайтеся, що існує достатній контраст між кольорами переднього плану та фону, щоб програмі зчитування з екрана було легко інтерпретувати його.

Заголовки

  • Використовуйте всі рівні заголовків, не пропускаючи рівні.
  • Розташуйте весь матеріал під заголовками, щоб полегшити читання.
  • Пам’ятайте, що в Markdown можна використовувати лише один заголовок першого рівня.

Підсумок

У цьому документі викладено наші стандарти щодо внеску, зокрема стильові рекомендації, як структурувати ваш документ і способи врахування інклюзивності та доступності в тексті. Це стандарти, до яких ми прагнемо. У міру своїх можливостей пам’ятайте про ці стандарти під час створення та редагування документації.

Однак — і не пропустіть це застереження — ставтеся до цих стандартів як до інструменту, а не як до перешкоди. У дусі інклюзивності та доступності ми хочемо забезпечити безперешкодне включення вашого внеску до генеалогічного дерева Роккі. Ми є дружньою командою документалістів і стилістів, які допомагають вам, і ми допоможемо привести ваш документ у його остаточний вигляд.

Ви готові? Давайте розпочнемо!

Author: Ezequiel Bruni, Krista Burdine

Contributors: Steven Spencer, Ganna Zhyrnova