Комментарии и упоминания

Зачем это нужно

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

Комментарии в Nextdocs прикреплены к конкретному месту в тексте.
Они остаются привязаны даже если вокруг текст полностью переписали.
Вся дискуссия — рядом со spec'ом, который она обсуждает.

Упоминания @ — способ позвать человека в дискуссию: ему придёт
уведомление с прямой ссылкой на этот комментарий.

Как оставить комментарий

1. Выделите фрагмент текста, по которому хотите что-то спросить /
   предложить.

2. Над выделением появляется всплывающая панель. Кнопка с иконкой
   «облачко разговора» → Comment.

3. Открывается панель справа (вкладка Comments в правом
   сайдбаре), туда автоматически подставлен цитируемый фрагмент.

4. Введите текст. Enter отправляет, Shift+Enter — новая строка,
   Escape — отменить.

На странице цитируемый фрагмент подсвечивается лёгким цветным
выделением. При клике по выделению — прокручивается к
соответствующему комментарию в правой панели и наоборот.

Что можно написать в комментарии

• Обычный текст, жирный / курсив через Cmd/Ctrl+B / Cmd/Ctrl+I.

• Упоминание — введите @, выберите человека из списка.

• Ссылки — просто вставьте URL, они автоопределятся. Ссылки на
  другие страницы Nextdocs работают как обычно.

• Перенос строки через Shift+Enter.

Длинные полотна кода / таблицы в комментарий лучше не пихать —
комментарии рассчитаны на короткие дискуссии, 1-5 предложений.

Треды

Ответить на комментарий — клик на плашку «Reply…» под ним. Открывается
мини-редактор. Ответ становится частью треда, показывается отступом.

Тред может содержать произвольное количество ответов. Chronology
сохраняется.

Resolve

Когда дискуссия завершена и вопрос снят — любой участник может
нажать Resolve. Комментарий визуально приглушается (становится
полупрозрачным), но не удаляется. При желании всегда можно открыть и
посмотреть историю обсуждения, или нажать Unresolve если
дискуссия снова актуальна.

Цель — держать активную дискуссию видимой, а старую — в архиве
ниже.

Удаление

Удалить комментарий может:

• Сам автор;

• Администратор проекта.

Удаление — необратимо, история треда пропадает. Обычно лучше
resolve'нуть, а не удалять.

Упоминания @

Где работают

• В тексте страницы — прямо в абзаце. Напишите @ив — список
  подскажет участников проекта с подходящими именами, выберите.
  В тексте появится чип «@Иван».

• В новом комментарии — тот же механизм. Упоминание в
  комментарии особенно полезно: «@Пётр, можешь подтвердить, что
  этот endpoint действительно deprecated?»

• В ответе на комментарий — аналогично.

Кто появляется в списке

• В тексте страницы и в комментариях — только участники данного
  проекта (не все пользователи системы). Это чтобы случайно не
  упомянуть человека, у которого нет доступа к странице.

• При приглашении новых участников в проект (отдельный модал) —
  поиск по всем пользователям, с которыми у вас есть хотя бы
  один общий проект. Это чтобы можно было быстро позвать
  знакомого коллегу без полного email.

Что происходит после упоминания

1. В момент отправки комментария / сохранения страницы — упомянутые
   получают уведомление.

2. В колоколе 🔔 в верхнем правом углу экрана появляется значок
   «непрочитанное».

3. Если упомянутый сейчас онлайн — всплывает toast-плашка с превью
   сообщения и кнопкой «Open».

4. Клик по уведомлению / по toast — переход на конкретную страницу,
   автоматически открывается панель с комментариями, прокручивается
   к упоминанию.

Дедуп

Если вы в одном комментарии упомянули одного человека 5 раз — он
получит одно уведомление. Если в течение 10 минут вы упоминали
этого же человека ещё раз в другом комментарии — тоже одно (в
activity feed), чтобы не спамить.

Уведомление через @ в personal notifications (колокольчик) — раз
в час от одного автора к одному получателю по одному ресурсу.

Навигация и глубокие ссылки

• Клик по любому комментарию в правой панели — скролл в тексте к
  цитируемому месту, выделение мигает.

• URL страницы может содержать #comment-{id} — откройте эту
  ссылку, и панель комментариев откроется автоматически на нужном
  месте. Это формат ссылок из уведомлений и ленты активности.

• Кнопка «скопировать ссылку» рядом с каждым комментарием — копирует
  deep-link в буфер.

Типовые сценарии

Ревью спеки. Продакт написал user story. Тимлид / команда
открывают страницу, проходят по разделам, выделяют неясные места,
оставляют inline-комментарии. Продакт отвечает, дописывает детали.
Каждую ветку дискуссии после ответа закрывают через Resolve. В итоге
в документе остаётся «чистая» спека, а обсуждение — в истории
комментариев.

Флаг противоречия. Заметили, что раздел А противоречит разделу
Б. Выделяете пометку «@Мария тут и в разделе “Security” —
противоречие, что правильно?». Мария видит уведомление, заходит,
правит, ставит Resolve.

Вопрос к автору. Читаете документацию по чужому проекту. Что-то
неясно. Выделяете, @автор, что имелось в виду?. Не выходите из
контекста чтения — и получите ответ прямо здесь.

Ограничения

• Максимум ~2000 символов в одном комментарии (мягкий лимит, для
  длинных обсуждений логичнее создать страницу).

• Вложения (картинки, файлы) в комментариях пока нельзя — только
  ссылки.

• Emoji-реакции на комментарии (like,
  thumbsup) — в планах.

• Оффлайн-комментарии не поддерживаются: комментарий не отправится,
  пока не восстановится соединение.