в первой итерации тоже меняли только шрифты и цвета, тоже не требовало разработки, но у Ozon есть своя дизайн-система и вот подогнать под неё уже сложнее;
у нас так же каждый раздел в отдельном репозитории и есть один — с темой, откуда и тянутся стили;
базовые элементы md, например, заголовки, тоже нет необходимости приправлять шорткодами) а вот куски текста, которые должны отображаться по-разному в разных странах — по-моему, даже в DITA надо чуть повозиться с настройками;
и в hugo так же есть файл глобальных настроек, где можно настраивать и сам факт отображение каких-то элементов, и их внешний вид.
Поэтому всё ещё скажу, что md кажется мне проще ADoc, тем более для людей совсем без опыта работы с docs-as-code.
как вы до сих пор используете Jira/Confluence
Вот тут не отвечу — это вотчина наших админов, мы просто используем доступные внутри компании ресурсы)
Md выиграл своей популярностью среди команды и причастных к переезду людей. Посмотрели на adoc, примерили, поняли, что надо привыкать и вникать и ушли в md. Тем более что в ssg в любом случае надо было дорабатывать элементы — так что чистого языка разметки всё равно не получилось бы. Вот и выбрали привычный для команды.
У Idea адекватное превью, с картинками и таблицами, но да, несколько файлов в один она не соберёт. В целом Jet Brains анонсировали нечто для техписов: https://lp.jetbrains.com/writerside/ — ждём, надеемся)
Всё так, храним версии оферт в pdf, но в общем объеме документации генерация pdf пока не требовала оптимизации. Но спасибо за столько вопросов — действительно надо поисследовать)
Пока таких ситуаций не возникало. Думаю, так же из md-файлов сделаем html или pdf через pandoc или подобную утилиту и распечатаем)
Но приоритетным вариантом всё же попытаемся убедить в достаточности онлайн-версии. Можно, например, настроить доступ только из конкретной подсети, если документ не должен быть публичным. Но любые физические артефакты и тот же pdf устаревают слишком быстро, поэтому мы всеми силами стараемся избегать таких документов.
Мы не особо используем pdf, наоборот стараемся всю документацию перевести онлайн, чтобы у пользователей не было "точно_последняя_инструкция_fin(5).pdf". Но да, версии оферт, например, надо хранить — тогда мы копируем нужный md-файл в отдельную папку со всеми изображениями, руками делаем оглавление через якори (### <a id="n">) и дальше в любой конвертер md-to-pdf. Но это удобно только для единичных страниц, признаю, глобально мы стараемся не использовать pdf.
Да, юридические политики и регламенты, обязательные к подписанию — это вотчина всё же юристов. Задача техписателей (в моём мире) всё же переводить на язык читателя. При этом юристу будет понятен и привычен полный текст, скорее всего, а вот для других аудиторий, как правильно отмечено, может хватить и презентации)
Главное, чтобы политики в итоге выполнялись, для этого надо объяснять как и почему их надо выполнять тем форматом, который наиболее понятен читателю. Считаю, что это задача для техписателей. HR, конечно, будут частью процесса составления, но тексты я бы отдала техписам)
Ну и ладно) зато сразу определены вопросы, которые стоит покрыть в первую очередь. Да и вряд ли у продукта нет вообще никакой доки — скорее всего хоть кто-то что-то себе записывал для удобства. И сейчас всё чаще вижу людей, которым удаётся на старте доказать, что документация нужна и важна (если это действительно так).
Всё так) поэтому надо думать что мы вообще пишем и для кого. Очень часто для понимания системы достаточно простой заметки, вместо талмуда с полным описанием каждого узла. Вопрос только, что иногда есть внешние требования
Спасибо, очень подробно расписали!
в первой итерации тоже меняли только шрифты и цвета, тоже не требовало разработки, но у Ozon есть своя дизайн-система и вот подогнать под неё уже сложнее;
у нас так же каждый раздел в отдельном репозитории и есть один — с темой, откуда и тянутся стили;
базовые элементы md, например, заголовки, тоже нет необходимости приправлять шорткодами) а вот куски текста, которые должны отображаться по-разному в разных странах — по-моему, даже в DITA надо чуть повозиться с настройками;
и в hugo так же есть файл глобальных настроек, где можно настраивать и сам факт отображение каких-то элементов, и их внешний вид.
Поэтому всё ещё скажу, что md кажется мне проще ADoc, тем более для людей совсем без опыта работы с docs-as-code.
Вот тут не отвечу — это вотчина наших админов, мы просто используем доступные внутри компании ресурсы)
Нашего — нет, он сильно нами дотюнен. Есть похожий по структуре: https://themes.gohugo.io/themes/hugo-book/
Сейчас вот этот используем: https://github.com/nextapps-de/flexsearch. Но изучаем эластик и собираемся переходить на него в обозримом будущем
Md выиграл своей популярностью среди команды и причастных к переезду людей. Посмотрели на adoc, примерили, поняли, что надо привыкать и вникать и ушли в md. Тем более что в ssg в любом случае надо было дорабатывать элементы — так что чистого языка разметки всё равно не получилось бы. Вот и выбрали привычный для команды.
А расскажете подробнее?) Как именно генерируете? Может, какие-то неочевидные проблемы всплыли?
Сейчас используем один из стандартных: https://gohugo.io/tools/search/
Но в перспективе смотрим как прикрутить поиск по всему docs.ozon, а не по одному документу — в такое hugo не умеет)
У Idea адекватное превью, с картинками и таблицами, но да, несколько файлов в один она не соберёт. В целом Jet Brains анонсировали нечто для техписов: https://lp.jetbrains.com/writerside/ — ждём, надеемся)
Всё так, храним версии оферт в pdf, но в общем объеме документации генерация pdf пока не требовала оптимизации. Но спасибо за столько вопросов — действительно надо поисследовать)
Да, Obsidian тоже использовала для проб разных генераторов и для личных заметок)
у pandoc есть генерация pdf, думаю можно попробовать через него
Пока таких ситуаций не возникало. Думаю, так же из md-файлов сделаем html или pdf через pandoc или подобную утилиту и распечатаем)
Но приоритетным вариантом всё же попытаемся убедить в достаточности онлайн-версии. Можно, например, настроить доступ только из конкретной подсети, если документ не должен быть публичным. Но любые физические артефакты и тот же pdf устаревают слишком быстро, поэтому мы всеми силами стараемся избегать таких документов.
Мы не особо используем pdf, наоборот стараемся всю документацию перевести онлайн, чтобы у пользователей не было "точно_последняя_инструкция_fin(5).pdf". Но да, версии оферт, например, надо хранить — тогда мы копируем нужный md-файл в отдельную папку со всеми изображениями, руками делаем оглавление через якори (### <a id="n">) и дальше в любой конвертер md-to-pdf. Но это удобно только для единичных страниц, признаю, глобально мы стараемся не использовать pdf.
Да, юридические политики и регламенты, обязательные к подписанию — это вотчина всё же юристов. Задача техписателей (в моём мире) всё же переводить на язык читателя. При этом юристу будет понятен и привычен полный текст, скорее всего, а вот для других аудиторий, как правильно отмечено, может хватить и презентации)
Главное, чтобы политики в итоге выполнялись, для этого надо объяснять как и почему их надо выполнять тем форматом, который наиболее понятен читателю. Считаю, что это задача для техписателей. HR, конечно, будут частью процесса составления, но тексты я бы отдала техписам)
В целом о том, что "должен" делать техписатель можно тоже долго спорить — всё очень сильно зависит от компании