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

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

При работе над документацией также нужно держать фокус на ограниченном объёме: после успешного Preview затем отправляйте Change Request.

Выберите способ отправки

• Если у вас уже есть права на редактирование в GitBook: создайте Change Request в соответствующем языковом пространстве;
• Если прав на редактирование нет: в Cherry Studio откройте 【Настройки】→【О нас】→【Обратная связь】 и укажите адрес страницы, проблему и предложение;
• Если проблема документации связана с изменениями кода: в кодовом PR отметьте пункт документации и приложите соответствующий Change Request или укажите, что обновление не требуется.

Процесс внесения изменений в GitBook

1

1. Создайте Change Request

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

2

2. Сначала проверьте текущий продукт

Сверьте входные точки, кнопки, значения по умолчанию и ожидаемые результаты по текущему интерфейсу Cherry Studio. Если структура старой страницы не совпадает с текущим продуктом, нужно заново перестроить содержание, а не просто заменить несколько терминов.

3

3. Пишите страницу под задачу пользователя

В начале поясните, что можно выполнить, затем дайте точный путь, пронумерованные шаги, ожидаемый результат, пояснения по настройке, реальные примеры и частые вопросы. В руководстве по настройке можно сначала предложить пользователю получить помощь от Agent в разделе 【Работа】, а затем дать ручной путь в 【Настройках】.

4

4. Используйте встроенные блоки GitBook

Для подсказок используйте Callout, для последовательных действий — Stepper, для частых вопросов — сворачиваемые блоки, для связанных страниц — Cards. Не оставляйте {% hint %}на странице как обычный текст теги HTML или разметку Markdown.

5

5. Добавляйте реальные скриншоты

Скриншоты должны быть из текущего интерфейса продукта, на упрощённом китайском, в светлой теме и единообразного размера. Отмечайте только те места, куда читателю нужно нажать или на что смотреть, а API Key, email, локальные пути и пользовательские данные закрывайте.

6

6. Предпросмотр и отправка на проверку

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

Требования к написанию страниц

Содержимое	Требование
Путь действий	Используйте названия, видимые в интерфейсе, например 【Работа】→【Добавить агента】
Термины	При первом упоминании объясняйте значение термина и его назначение
Параметры	Различайте значения по умолчанию в продукте и рекомендуемую отправную точку, объясняйте назначение и риски
Примеры	Используйте конкретные роли, цели, входные данные и результат
Скриншоты	Из реального интерфейса, с альтернативным текстом и пронумерованными пояснениями
Ссылка	Ссылайтесь на текущую страницу или официальный источник и перед отправкой откройте каждую ссылку по отдельности

Замечания по скриншотам

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

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

Проверка читателем

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

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

Чек-лист самопроверки

• Нет старых входных точек, старых названий или устаревших функций;
• Нет жёстко зафиксированных нестабильных рейтингов моделей, цен и «лучшей конфигурации»;
• Нет версий, даты проверки или внутренних путей реализации, которые прерывают чтение;
• Названия интерфейса единообразно оформлены в 【】;
• Текст читается как написанный редактором продукта для пользователя, а не как автоматически сгенерированный отчёт;
• Каждый шаг можно начать из соответствующего пункта в текущем интерфейсе;
• Изображения, ссылки и встроенные блоки GitBook корректно отображаются в Preview.

Можно ли напрямую редактировать опубликованную страницу?

Нет. Используйте Change Request, чтобы сохранить объём изменений и процесс проверки; после подтверждения всё объединит человек с нужными правами.