Доработка документации

documentation/ru/docs/features/interaction-bot.md

@@ -6,7 +6,7 @@
 
     На данный момент главное меню содержит только пункт: "Добавить новый репозиторий". В будущем функционал существенно расширится.
 
-## Добавить новый репозиторий
+## Добавить новый репозиторий { id="add-new-repository" }
 
 Если во время первичной инициализации не стали добавлять все доступные репозитории, или не включили автоматическое отслеживание появления новых репозиториев, то вы можете добавлять репозитории самостоятельно.
 
@@ -28,3 +28,14 @@
     https://gitlab.com/groupname/projectname1/repositoryname2
     https://gitlab.com/groupname/projectname2/repositoryname3
     ```
+
+
+## Быстрые действия { id="fast-actions" }
+
+Быстрые действия выглядят в виде кнопок под уведомлением, и позволяют в одно нажатие изменять настройки бота.
+
+Самые частые быстрые действия:
+
+- :eyes: — прочитано. Просто удаляет сообщение.
+- :link: — ссылка для перехода в GitLab.
+- :no_bell: — отключить уведомления данного типа.

documentation/ru/docs/features/interaction-gitlab.md

@@ -1,5 +1,16 @@
+---
+description: Отправляйте события из Telegram в GitLab
+
+---
+
 # Взаимодействие с GitLab
 
+Здесь собраны все возможности, которые позволяют вам что-то сделать в GitLab прямо из Telegram.
+
+!!! warning
+
+    Все эти функции работают, если при создании GitLab токена вы указали уровень доступа `api`.
+
 ## Ответ в треде
 Допустим вас упомянули в обсуждении, сразу знаете что ответить? Не тратьте время, отвечайте прямо из телеграм. Для этого просто ответьте на сообщение и напишите ваш комментарий.
 

documentation/ru/docs/features/notify.md

@@ -1,17 +1,23 @@
-# :bell: Уведомления
+---
+description: Основное предназначение бота - это уведомления от GitLab. Вы будете получать только персональные уведомления.
+
+---
+
+# :bell:{ .jingle-bell } Уведомления
 Основное предназначение бота - это уведомления от GitLab. Вы будете получать только те уведомления, которые касаются вас непосредственно.
 
 ## Новый репозиторий { id="new-repository" }
-Если во время первичной настройки вы указали, что хотите получать уведомления о новых репозиториях, то при появлении нового репозитория получите соответствующее уведомление:
+Если во время [первичной настройки](../getting-started/first-start.md) вы указали, что хотите получать уведомления о новых репозиториях, то при появлении нового репозитория получите соответствующее уведомление:
 <figure markdown>
 ![notify about new merge request](img/notify-new-project.png){ loading=lazy width="500" }
 </figure>
 
 Уведомление содержит:
 
-- Project name — название репозитория.
+- GitLab Notify — название репозитория.
 - Project description — описание репозитория. Опционально, может быть пусто.
-- Struchkov Mark — имя создателя репозитория в GitLab
+- ssh, http — ссылки на удаленный репозиторий. При нажатии будет скопирована в буфер обмена.
+- Author Name — имя создателя репозитория в GitLab
 
 Доступно три быстрых действия:
 
@@ -19,7 +25,7 @@
 - :bell: — поставить на отслеживание. Вы начнете получать уведомления о событиях в MR, тредах и сборках.
 - :no_bell: — не получать уведомления. Используется по умолчанию, по факту просто удаляет сообщение уведомления.
 
-!!! warning ""
+!!! warning "Отслеживание репозитория"
 
     Пока вы явно не нажмете :bell:, вы не будете получать никаких уведомлений. Более того, приложение даже не будет запрашивать MR и прочие сущности репозитория, не будет сохранять их в БД.
 
@@ -46,7 +52,7 @@
 - :link: — ссылка на MR.
 - :no_bell: — не получать уведомления по MR.
 
-!!! warning ""
+!!! warning
 
     Учтите, что отключение уведомлений отключает только уведомления об изменениях в MR. Например, обновление статуса MR. Но уведомления по пайплайнам проекта, по тредам MR продолжат приходить.
 
@@ -84,7 +90,7 @@
 - :link: — ссылка на MR.
 - :no_bell: — не получать уведомления по этому MR.
 
-## Изменение статуса MR
+## Изменение статуса MR { id="status-mr" }
 Когда статус вашего MR меняется, вы получаете уведомление.
 
 <figure markdown>
@@ -96,7 +102,7 @@
 - :eyes: — прочитано. Удаляет сообщение.
 - :link: — ссылка на MR.
 
-## Новый тред в MR
+## Новый тред в MR { id="new-thread" }
 В GitLab можно создавать не просто комментарии, а треды. Если кто-то создаст такое обсуждение в вашем MR, то вы сразу об этом узнаете.
 
 Это уведомление поддерживает уровни конфиденциальности:
@@ -134,7 +140,7 @@
 - :link: — ссылка на тред.
 - :no_bell: — не получать уведомления по этому треду. Уведомления по другим тредам в это MR продолжат поступать.
 
-## Новое сообщение в треде
+## Новое сообщение в треде { id="new-thread-answer" }
 
 Важно оставаться в теме обсуждения, поэтому при появлении новых ответов в тредах, в которых вы участвовали, вы получите уведомление.
 
@@ -178,16 +184,17 @@
 - :link: — ссылка на тред.
 - :no_bell: — не получать уведомления по этому треду. Уведомления по другим тредам в это MR продолжат поступать.
 
-### Упоминание в треде
+### Упоминание в треде { id="mention-in-thread" }
 Допустим, кто-то упомянул вас в MR используя тегирование GitLab (@GitlabLogin). Автор этого MR не вы, ответственным назначали тоже не вас. 
 
 Если вы отслеживаете репозиторий этого MR, но не участвовали в дискуссии, то в этом случае вам придет уведомление. Так вы не пропустите сообщения с вашим упоминанием.
 
 Формат и быстрые действия такие же, как у уведомления "Новое сообщение в треде".
 
-## Уведомление о решенном треде
+## Уведомление о решенном треде { id="resolved-thread" }
+Если кто-то отметит решенным созданный вами тред, вы получите уведомление об этом.
 
-## Уведомление о пайплайне
+## Уведомление о пайплайне { id="new-pipeline" }
 Полезно сразу узнавать, что сборка закончилась успешно или упала.
 
 !!! question "Я буду получать уведомление обо всех пайплайнах?"

documentation/ru/docs/getting-started/configuration.md

@@ -1,4 +1,4 @@
-# Первый запуск ассистента
+# Первый запуск бота
 
 Есть несколько способов запустить бота-помощника. Бот был спроектирован таким образом, чтобы работать локально на вашем ПК, но вы можете запустить его на сервере в режиме 24/4.
 
@@ -7,7 +7,7 @@
 1. [Создание бота в Telegram](creating-telegram-bot.md)
 2. [Получение персонального токена в GitLab](create-gitlab-token.md)
 
-## Конфигурация
+## Переменные среды { id="env" }
 Вне зависимости от того, какой способ вы выберете, необходимо будет указать данные переменные среды:
 
 * `TELEGRAM_BOT_TOKEN` — токен, который вы получили при [создании бота](creating-telegram-bot.md).

documentation/ru/docs/getting-started/first-start.md

@@ -1,4 +1,6 @@
-# Инициализация бота
+# Первичная настройка
+
+Первичная настройка выполняется один раз после первого запуска бота. Она позволяет задать первоначальную конфигурацию поведения сканирования и прочих параметров.
 
 В данном видео демонстрируется процесс первичной настройки бота, чтобы вы знали, чего ожидать:
 

documentation/ru/docs/index.md

@@ -1,29 +1,35 @@
 ---
-title: Быстрый старт
+title: GitLab Notification in Telegram
 hide:
     - toc
     - comments
-
+description: Персональный бот в Telegram поможет вам оставаться в курсе изменений, которые касаются вас непосредственно.
 ---
 
 # GitLab Notification – Персональный Telegram бот для GitLab
-Персональный ассистент призван упростить работу с GitLab. Получайте персональные уведомления о событиях в GitLab, ничего не пропустите и не забудьте.
+Запустите своего личного GitLab бота и получайте персональные уведомления из GitLab прямо на свой аккаунт в Telegram! Это не облачное решение, бот запускается на вашей машине или вашем сервере.
 
-Бота-ассистента можно запустить как для облачного GitLab, так и для Self-host решений.
+Вы больше никогда не пропустите важное уведомление. Будь то новый запрос на слияние или возникновение конфликта. Больше не нужно заходить в GitLab, чтобы проверить статус сборки - с нашим приложением вы сможете оставаться в курсе дел, где бы вы ни находились.
 
-!!! info "GodFather Telegram"
+Бота легко [настроить и использовать](getting-started/configuration.md), а быстрые действия призваны оптимизировать ваш рабочий процесс. Не ждите больше - запустите своего персонального Telegram бота, и получайте персональные уведомления о событиях в GitLab.
 
-    Данный проект использует другой мой проект GodFather Telegram для создания Tlegram ботов различной сложности.
+<figure markdown>
+  ![notify-about-new-mr](features/img/notify-new-mr.png){ loading=lazy width="600" }
 
-## Основные возможности
+  <figcaption>Пример уведомления от бота</figcaption>
-- Уведомление о появлении нового репозитория.
+</figure>
-- Уведомление о новых MR.
+
-- Уведомление о возникновении конфликта в MR.
+!!! question "Что-то здесь не чисто"
-- Уведомление о смене статуса вашего MR.
+
+    Я понимаю, что GitLab часто содержит конфиденциальные данные, утечка которых не желательна. Поэтому я оформил [отдельную страницу, на которой собрал ответы на вопросы безопасности и конфеденциалоьности.](privacy/index.md)
+
+## Основные возможности { id="key-features" }
+- Уведомление о новых MR, где вы ревьювер или ответственный.
+- Уведомление о результате работы сборки.
+- Уведомление о возникновении конфликта в вашем MR.
 - Уведомление о треде, в которых вас упоминают в формате @nickname.
-- Уведомит о новом треде в вашем MR.
+- Уведомление о смене статуса вашего MR.
-- Уведомит о закрытии вашего треда в чужом MR.
+- [И многое многое другое...](features/notify.md)
-- Уведомление о результате сборки.
 
 ***
 

documentation/ru/docs/privacy/index.md

@@ -1,27 +1,40 @@
-# :ninja: Конфиденциальность
+---
+description: Эта страница пытается ответить на все вопросы, которые могут вас смущать.
 
-Я разработчик, и это приложение должно помогать мне работать, оптимизируя мое время взаимодействия с GitLab. В какой-то момент я решил подлиться своими наработками со всеми желающими. Часто в GitLab содержится множество конфиденциальной информации, которую не хотелось бы раскрывать. Эта страница пытается ответить на все вопросы, которые могут вас смущать.
+---
 
-!!! tip "Доверие"
+# :ninja:{ .ninja-disappear } Защита данных
 
-    Вы не должны верить мне на слово. Вы можете [самостоятельно изучить код, он открыт и не сложен.](https://github.com/uPagge/gitlab-notification) После проверки можно самостоятельно собрать jar и [упаковать его в Docker](https://github.com/uPagge/gitlab-notification/blob/master/Dockerfile). Либо запускать код прямо из Idea.
+Я понимаю, что в GitLab содержится множество конфиденциальной информации, которую не хотелось бы раскрывать. Эта страница пытается ответить на все вопросы, которые могут вас смущать.
 
-## Защита токена GitLab
+## Об авторе бота { id="about-author" }
-Для работы ассистента необходим персональный токен GitLab. Он указывается в переменные среды и нигде дополнительно не хранится и не передается. Таким образом токен не попадает в Telegram и хранится только у вас на компьютере и в контейнере приложения.
 
-Токен используется только при обращении к указанному GitLab, и только для выполнения описанных в документации возможностей. Никакой скрытой работы не выполняется, по возможности обо всех взаимодействиях с GitLab дополнительно сообщается во время настройки.
+Давайте знакомится. Меня зовут [Стручков Марк](https://mark.struchkov.dev), я тимлид небольшой команды. В свободное время веду [блог](https://struchkov.dev/blog) и ["блокнот."](https://note.struchkov.dev) ==Это приложение в первую очередь должно помогать мне работать, оптимизируя мое взаимодействие с GitLab.==
 
-!!! question "А что, если ты заполучишь токен?"
+В какой-то момент я решил подлиться своими наработками со всеми желающими. И пытаться кому-то что-то доказать у меня нет желания. ==Что-то смущает? Не пользуйтесь.== В этом весь Open Source.
 
-    Ну начнем с того, что мне ваш токен даром не нужен. Изучайте код, если мне не верите, или не пользуйтесь моим ботом. Эта страница призвана ответить на возникающие вопросы безопаности решения, не более этого. Дополнительно убеждать никого не собираюсь.
+Вы можете [самостоятельно изучить код, он полностью открыт, доступен, и не сложен.](https://github.com/uPagge/gitlab-notification) После проверки можно самостоятельно собрать `jar` и [упаковать его в Docker](https://github.com/uPagge/gitlab-notification/blob/master/Dockerfile). Либо запускать прямо из Idea.
 
-## Уровни конфиденциальности
+На мой взгляд довольно очевидно, что если бы я преднамеренно замышлял какую-нибудь пакость, то не стал бы делать это от своего имени. Однако некоторые вектора атаки существуют, и я постараюсь описать их на этой странице.
 
-Некоторые уведомления могут содержать множество чувствительной информации. Например, уведомления о новых сообщениях в тредах. Возможно вы не захотите раскрывать столько информации о вашей разработке телеграму, ведь через него идет получение уведомлений. Специально для таких случаев предусмотрены уровни конфиденциальности разных типов уведомлений.
+## Защита токена GitLab { id="gitlab-token-protection" }
+Для работы ассистента необходим [персональный токен GitLab](../getting-started/create-gitlab-token.md). Достаточно токена с правами только на чтение. Он указывается в [переменные среды](../getting-started/configuration.md#env) и нигде дополнительно не хранится и не передается. Таким образом ==токен не попадает в Telegram, никуда не передается, и хранится только у вас на компьютере и в контейнере приложения.==
+
+==Токен используется только при обращении к указанному GitLab, и только для выполнения описанных в документации возможностей.== Никакой скрытой работы не выполняется, по возможности обо всех взаимодействиях с GitLab дополнительно сообщается в диалоговом режиме, особенно [во время первичной настройки](../getting-started/first-start.md).
+
+!!! question "А что, если ты украдешь токен?"
+
+    Я еще раз повторяю, что в мои планы не входит что-то кому-то доказывать. Это open source, детка, изучайте код и [позорьте мое честное имя](https://mark.struchkov.dev) перед сообществом, если что-то найдете.
+
+    Задайте себе вопрос: насколько полезен токен от вашего корпоративного self-host гитлаба без подключения к корпоративному VPN.
+
+## Уровни конфиденциальности { id="privacy-levels" }
+
+Некоторые уведомления могут содержать множество чувствительной информации. Например, [уведомления о новых сообщениях в тредах.](../features/notify.md#new-thread-answer) Возможно вы не захотите раскрывать столько информации о вашей разработке телеграму, ведь через него идет получение уведомлений. Специально для таких случаев предусмотрены уровни конфиденциальности разных типов уведомлений.
 
 Возьмем для примера уведомление о новом сообщении в треде. При минимальном уровне конфиденциальности вы получите уведомление с текстом комментария и сможете сразу ответить на него в телеграм, а при максимальном уровне конфиденциальности будет сообщаться только о факте нового комментария, без содержания. Все это настраивается при первом запуске.
 
-## Сохранение в БД
+## Сохранение в БД { id="database" }
 Для работы ассистента ему нужно сохранять предыдущее состояние GitLab сущностей. Для этого используется БД. Приложение старается не хранить в БД больше данных, чем необходимо. Как только необходимость в данных теряется, например MR мержится, данные из БД удаляются.
 
 Прочитать подробнее можно в разделе: [Работа с базой данных](../architecture/concept.md#schema-database)
@@ -41,4 +54,7 @@
   <figcaption>уведомление о несанкционированном доступе</figcaption>
 </figure>
 
-Для злоумышленника все выглядит так, как будто бот не работает. Никаких ответных сообщений ему не отправляется.
+Для злоумышленника все выглядит так, как будто бот не работает. Никаких ответных сообщений ему не отправляется.
+
+## Взлом Telegram { id="hack-telegram" }
+Если ваш Telegram аккаунт взломают, то взломщику станет доступна вся переписка с ботом. Поэтому рекомендую нажимать на [быстрое действие](../features/interaction-bot.md#fast-actions) о просмотре сообщения (:eyes:), а также периодически удалять историю переписки.

documentation/ru/docs/stylesheets/extra.css

@@ -14,6 +14,12 @@
     margin-top: 2.2rem;
 }
 
+.md-typeset mark {
+    background-color: #fff3bc;
+    margin: -4px -4px -6px;
+    padding: 4px 4px 6px;
+}
+
 @keyframes heart {
     0%, 40%, 80%, 100% {
         transform: scale(1);
@@ -26,6 +32,41 @@
     animation: heart 1000ms infinite;
 }
 
+@keyframes ninja-disappear {
+    0% {
+        opacity: 1;
+    }
+    50% {
+        opacity: 0.3;
+    }
+    100% {
+        opacity: 1;
+    }
+}
+
+.ninja-disappear {
+    animation: ninja-disappear 3000ms infinite;
+    animation-delay: 1500ms;
+}
+
+@keyframes jingle-bell-swing {
+    0% {
+        transform: rotate(0deg);
+    }
+    50% {
+        transform: rotate(10deg);
+    }
+    100% {
+        transform: rotate(0deg);
+    }
+}
+
+.jingle-bell {
+    animation: jingle-bell-swing 2s ease-in-out infinite;
+    transform-origin: center;
+}
+
+
 @media(min-width: 768px) {
     .frontpage-grid {
         display: grid;

documentation/ru/mkdocs.yml

@@ -7,7 +7,7 @@ edit_uri: edit/develop/documentation/ru/docs
 
 nav:
   - О проекте: index.md
-  - Конфиденциальность: privacy/index.md
+  - Защита данных: privacy/index.md
   - Возможности:
     - Уведомления: features/notify.md
     - Взаимодействие с GitLab: features/interaction-gitlab.md