Комментарии 6
У вас тут темная тема чтоли вылезла кое-где. https://docs.ozon.ru/api/retail/
На темном фоне не видно текста. В двух браузерах проверял.
Расскажите где пишите, верстаете, обновляете документацию. Что самописное, что используете из существующего. Как собираете левый столбец, он генерируется из заголовков или дублируете руками?
Привет! сейчас посмотрела Retail api, вроде бы всё ок, но я напишу коллегам, которые им занимаются :) спасибо
Вопросы отличные, кратко не ответить. Кажется, что нужно написать отдельную статью. У нас много разработок, я даже знаю разработчиков, которые создали основу публичной документации https://docs.ozon.ru/main.
Левые столбцы и оглавления справа генерируются автоматически, туда подтягиваются заголовки.
Я могу написать подробную статью, если интересно.
Вопрос скорее о ресурсозатратности. Если фронтов много, можно и там и сям задачки на самопис делать и поддерживать. А документация сервиса - задача типа интернет магазина: решения эволюционно созревшие выливаются в продукт, который не обязательно пилить с нуля. Например, https://docusaurus.io и вот интересно, был ли у вас какой скелет. Или сразу самопис, генератор статики... хотя у вас SPA и lodash еще используете... неужели надо...
Спасибо за статью, оказалась очень своевременно!
Из полезного, нашёл https://www.tango.us/ - бесплатное расширение в Chrome (есть платное дестктопное приложение) упрощающее создание гайдов и тп, есть экспорт в pdf, html и markdown.
Пример отличного мануала из другой статьи на хабре: https://habr.com/ru/company/mcn/blog/97854/#comment_3017639
Чтобы в Confluence хорошо искалось, нужно добавлять метки на странице.
Например, если на странице написано про kubernetes, то можно добавить метки "кубер", кубернетес, k8s, т.к. никогда не знаешь, по каким словам будет искать пользователь.
Составляем документацию разработчика пошагово без диет и тренировок