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

Привет! Как вы могли заметить, этот сайт документации полностью открыт и свободен для редактирования на GitHub. Вы можете увидеть страницу этого сайта на GitHub по адресу https://github.com/space-wizards/docs.

Есть пара вещей, которые стоит иметь в виду при внесении вклада. Хотя мы запрещаем PR с веб-редактированием (те, что сделаны исключительно на GitHub) в основных репозиториях Space Station 14 и Robust Toolbox, здесь это не так. Веб-редактирование приветствуется, чтобы сделать редактирование документации как можно более безболезненным.

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

Стиль

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

Внесение базовых правок

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

  1. Создайте аккаунт на GitHub или войдите, если он у вас уже есть.

  2. Форкните репозиторий space-wizards/docs на GitHub.

  1. Нажмите иконку ’View & Edit Page on GitHub` в самом правом верхнем углу любой страницы этого сайта.

  1. Нажмите кнопку ‘Edit this file’ в правом верхнем углу просмотра файла.

  1. Внесите свои изменения, затем закоммитьте и создайте pull request! Остальное мы возьмём на себя.

Сборка

Если вы хотите собрать документацию локально, необходимыми зависимостями являются Rust и некоторые бинарные файлы, устанавливаемые с помощью cargo. Рекомендуется использовать cargo install или cargo quickinstall, так как сборка может занять некоторое время.

Через cargo установите:

  • mdbook
  • mdbook-admonish
  • mdbook-embedify
  • mdbook-emojicodes
  • mdbook-linkcheck
  • mdbook-mermaid
  • mdbook-template

Запустите mdbook serve, чтобы собрать документацию и разместить её локально из каталога book по адресу localhost:3000.

Тестирование изменений

Если вы создали PR, самый простой способ проверить свои изменения, поскольку это всего лишь markdown, заключается в том, чтобы просмотреть их во встроенном просмотрщике markdown на GitHub на вкладке Files changed. Вы также можете использовать расширение локального предпросмотра markdown для чего-то вроде VSCode.

Если вы хотите немного более аутентичный опыт, для каждого PR будет запускаться действие Test mdBook Build & Upload Artifact, и вы можете скачать собранный сайт так:

Затем просто распакуйте его и откройте index.html. Наш кастомный CSS и всё такое будет работать не очень хорошо, но выглядеть будет достаточно сносно.

Для по-настоящему аутентичного опыта просто следуйте приведённым выше инструкциям по сборке и запустите mdbook serve как обычно.

Ревью

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

Чтобы помочь максимально эффективно использовать время мейнтейнеров на ревью, перед отправкой, пожалуйста:

  • Вычитывайте свои изменения
  • Используйте проверку орфографии
  • Подумайте об использовании инструментов проверки грамматики, таких как Grammarly

Subpages