(вот оригинальный, 20 лет ему уже, но он даже не особо устарел: https://www.joelonsoftware.com/2000/08/09/the-joel-test-12-steps-to-better-code/)

ты имеешь в виду вроде стандартов ISO или именно какие-то наши разделяемые конвенции внутренние?

А как вы относитесь к вставке видео в html-документацию?

положительно ) вставляем иногда ролики, которые выкладываем на ютуб

Я тут у одной компании подсмотрел. Там, в видео, объяснялась архитектура продукта и базово как поднять веб-сервер. Выглядело неплохо.

если с разработкой аналогию провести, то например стандартом индустрии сейчас является git. есть ли такое в документировании? чтобы можно было посмотреть на документацию и сказать: она соответствует стандартам индустрии. не знаю, описано ли это в ISO

У нас маркетинг делает ролики для пользователей. У них прямо запросы есть - сделайте нам видео

если прям стандарт для сертификации, то ICS 01.110. git мне не кажется стандартом, это система контроля версий, а вот например git flow и подходы к ведению веток - это уже больше смахивает на стандарт или там Python Styleguide например, я бы такого рода аналоги искала

тут я бы скорее вела речь (по аналогию с разработкой) про first and foremost technologies, что вот сейчас у них в моде кубер+гитлаб/гитхаб+прометей+графана стек

Лана, а зачем стек на метрики техписам?

я про разработку

first и foremost technologies, кажется, не совсем про нас — все-таки у каждой команды плюс-минус свой стек: у кого-то выстраданные локальными требованиями узкоспециальные SSG, у кого-то Help&Manual, у кого-то только Confluence

а вот список рекомендованных практик и типовых инструментов для них — это норм, что-нибудь типа:

- Документацию можно хранить в гите. Вот случаи, когда это удобно, а вот когда неудобно. Вот список из 10 годных SSG
- Если вам нужно генерить документационный сайт из нескольких репозиториев сразу, то вот SSG, которые это умеют
- Если у вас RESTful HTTP API, то смотрите в сторону OpenAPI, и вот набор тулинга для работы с ним (не Сваггером единым!)
- Иногда вам нужен single source и множественные выходные форматы. Вот тулинг, на который стоит посмотреть в этой связи
- Confluence и вики-системы: вот когда они хороши, а вот когда не очень
- Если вам нужно генерить PDF, то вот в какую сторону стоит посмотреть
- Вот типовые workflow разработки документации, вот как их можно реализовать на каждом из обсужденных выше инструментов

использование single source и контроля версий. по стилю на русском не знаю. есть ру терминология из Майкрософт. может, и стайлгайд у них русский еще есть. Яндекс какие-то стандарты у себя используют, наверно.

А у вас есть доклад на эту тему?)

а может сделаем условно репозиторий в гитчем-то и напишем манифест сообщества, куда как раз эту информацию и запишем?)

краудсорсно

👍

Технорадар для этой задачи неплохо подходит. https://www.thoughtworks.com/radar
Мы в Plesk такой делали для команды техписателей. Возможно, я смогу поделиться им.

а можно ли в техрадар записывать подходы, а не инструменты?

Да, там есть четыре сектора, один из них как раз про подходы.