OridocДокументация к продукту, которую проще вести, чем в Word
Импортируйте руководство из Word, правьте его как обычный документ и нажмите «Опубликовать». Получится быстрый сайт с поиском, который встраивается в продукт. Вести его может тот, кто знает продукт: писатель, аналитик, поддержка, руководитель.
- Начало работы
- Интерфейс
- Уведомления
- Настройка уведомлений
- Каналы доставки
- Люди и доступ
Настройка уведомлений
Оператор получает уведомление, когда система фиксирует событие на объекте. Каналы доставки настраиваются отдельно для каждой группы событий, поэтому дежурная смена и руководитель видят разные списки.
Чтобы включить доставку, откройте раздел «Каналы» и выберите способ связи для каждой группы.
Руководство на двести страниц никто не читает
Не найти.
Поиск по файлу ищет слова, а не ответы. Оглавление на сорок пунктов не помогает.
Устаревает целиком.
Правка одного абзаца тянет пересогласование всего документа, поэтому правок не делают.
Не открыть с нужного экрана.
Файл нельзя встроить в продукт и нельзя сослаться на него из интерфейса.
Три шага от файла до сайта
Импортируйте.
Нажмите «Импортировать из Word». Каждый заголовок верхнего уровня станет страницей, картинки переедут сами. Что не перенеслось — программа назовёт сразу.
Пишите.
Страница на экране выглядит так, как её увидит читатель. Скриншот вставляется из буфера обмена, ссылка на другую страницу выбирается из списка — битых не бывает.
Опубликуйте.
Одна кнопка собирает сайт и проверяет его. С битой ссылкой наружу ничего не уйдёт. Сайт ляжет в папку, в сетевую папку или в репозиторий — куда скажете.
Что умеет
Редактор, структура, картинки, сборка и публикация — всё, чтобы довести документацию от первой страницы до сайта, который открывают читатели.
Страница как документ
Абзацы, заголовки, списки с вложенностью, таблицы, выноски трёх видов и блоки кода. Страница показывается так, как её увидит читатель.
Разделы и страницы
Порядок задаётся перетаскиванием, страница переносится между разделами. Переименование и перенос чинят ссылки во всей документации сами.
Битых ссылок не бывает
Ссылка выбирается из списка страниц, а не набирается руками. Удаление страницы предупреждает, кто на неё ссылается.
Картинки и скриншоты
Вставка из буфера обмена, перетаскивание файла, SVG с очисткой от скриптов. Устаревший скриншот заменяется во всех местах разом.
История правок
Перед каждой перезаписью Oridoc снимает копию страницы. Вернуться можно к любой версии.
Поиск без сервера
По всему тексту, с переходом сразу к нужному заголовку. Словарь синонимов: «сброс пароля» находит «восстановление пароля».
Проверки перед публикацией
Битые ссылки, пропавшие картинки, отсутствующие якоря заголовков. Найденные ошибки останавливают публикацию.
Оформление и значки
Темы с наследованием, фирменный цвет с подбором оттенка для тёмного режима, логотип и справочник значков для разделов.
Публикация в три места
Оставить в папке проекта, разложить в общую папку или отправить в репозиторий отдельной веткой. Репозиторий не обязателен.
Обновление по кнопке
Программа сама замечает новую версию, скачивает её и подменяет себя. Подлинность проверяется подписью; не подтвердилась — программа скажет об этом и ставить не станет.
Импорт из Word
Из каждого заголовка верхнего уровня выходит отдельная страница, картинки переносятся в проект. Импорт занимает минуту, разобрать получившееся — час: против недели ручного переноса это другой порядок.
Читатель не увидит битую ссылку
Перед сборкой Oridoc проверяет документ целиком: ссылки, якоря заголовков, картинки, служебные заголовки страниц, значки разделов. Если что-то не сходится, публикация останавливается и показывает, где именно.
От каждой ошибки есть переход прямо к месту в тексте, поэтому разбор занимает минуты, а не вечер.
- Ссылка на удалённую страницу «Роли»
- Картинка «панель-событий.webp» не найдена
- Страница «Журнал» без служебного заголовка
- Якоря заголовков — 148 проверено
Ведёт тот, кто знает продукт
Технический писатель
Умеет писать, не должен уметь программировать. Работает с текстом, а не с разметкой.
Аналитик
Описание функции, которое он всё равно пишет, становится страницей документации, а не остаётся в задаче.
Поддержка
Вопрос, который задали в третий раз, становится страницей, и в четвёртый раз на него отвечает ссылка.
Руководитель или основатель
Ведёт документацию сам, пока писателя нет, и не стыдится результата.
Разработчик встраивает готовый сайт в продукт один раз. Читатель находит ответ за минуту.
Проект, документы и сайты
Проект объединяет документы об одном и том же: оформление, картинки и значки у них общие. Внутри — документы: руководство пользователя, руководство администратора, документ по ГОСТ. У каждого свой сайт.
Общая папка
Оформление, картинки, справочник значков. Живёт у вас на диске или в вашем репозитории — Oridoc заведёт папку сам и покажет, где она.
Книги внутри проекта
У каждого документа свои разделы, своя обложка — её движок рисует сам — и свой сайт. Программа открывается галереей проектов, а не последним выбранным.
Статические страницы
Боковая навигация, оглавление страницы, поиск, светлое и тёмное оформление, вёрстка под телефон и версия для печати. Сервер приложений не нужен.
Частые вопросы
Чем это лучше Word?
Тем, что читатель находит ответ, а не листает двести страниц: поиск по всему тексту, оглавление, ссылка на нужную страницу прямо из продукта. А правка одного абзаца не требует пересогласовывать весь документ. Word при этом никуда не девается: руководство импортируется из него за минуту.
Нужно ли уметь программировать?
Нет. Скачайте, откройте, работайте: это обычная программа с окном. Командная строка есть для тех, кому она удобнее.
Можно ли перенести руководство из Word?
Да. Из каждого заголовка верхнего уровня выходит страница, картинки переносятся в проект: руководство на двести страниц становится полусотней страниц документации. Импорт занимает минуту, разбор получившегося — час, и программа сразу называет то, что не перенеслось. Связи с файлом не остаётся: это переезд, а не связка, и правки в Word обратно не приедут.
Где хранятся тексты и нужен ли git?
Проект — обычная папка на вашем диске, страницы в ней — обычные текстовые файлы. Git не обязателен: публиковать можно в папку проекта или в общую папку на сервере. Если репозиторий есть, Oridoc отправит собранный сайт отдельной веткой. На наш сервер текст не уходит.
Можно ли работать над документацией вдвоём?
Пока нет. Продукт рассчитан на одного писателя: двое на одной странице затрут правки друг друга, ролей и отправки на проверку тоже пока нет.
Нужен ли сервер, чтобы открыть готовую документацию?
Нет. На выходе получается статический сайт: файлы можно положить на любой хостинг, во внутреннюю сеть или прямо в дистрибутив продукта. Поиск работает у читателя в браузере, без обращений к серверу.
Подойдёт ли Oridoc для внутренней вики?
Для вики есть инструменты лучше. Oridoc — для документации, которую читают пользователи продукта. Он не заменяет вики для внутренних знаний, систему задач и базу знаний поддержки, и не редактирует произвольный Markdown из чужого репозитория.
Чем Oridoc отличается от статических генераторов?
Генераторы требуют инженера: разметка, git, сборка, пайплайн. Технический писатель, который умеет писать, но не умеет программировать, до них не доходит. В Oridoc всё это остаётся внутри программы: писатель видит документ и кнопку «Опубликовать».
Попробуйте на своём руководстве
macOS и Windows. Бесплатно, без регистрации.