Комментарии 7
Забыли про самый главный стайлгайд - ГОСТы 19, 34. И главный его смысл не каким шрифтом писать текст или в каком редакторе стрелочки рисовать, а перечень разделов, которые должны быть в документации. Ибо не все аффторы догадываются что должны быть такие разделы, например, как "Резервное копирование" и "Восстановление" )))
Строго говоря в статье описано руководство по "Стилю", а не функциональные требования
В целом, про ГОСТы я написала. Просто не стала уточнять какие именно обычно используются.
Согласна, что оформление статей это не самая важная часть, наполнение важнее, но в нашем стайлгайде как раз этому моменту мы уделили не мало внимания. В разделе, где описывается структура статей и разделов документации мы расписали какие статьи обычно требуются и что ожидается внутри. А в прошлой статье рассказывали о том, что также создавали для некоторых статей шаблоны.
Классный обзор и круто, что делитесь примерами правил, для русского и правда мало такого, вспоминается только Макйрософт. Планировали ли или может уже внедряете автоматические проверки относительно стайлгайда, на уровне текстового редактора/локально или на уровне CI/CD? Думали ли внедрять линтеры, например, Vale?
Очень интересно, может что-то понял.
Стайлгайд обязателен, без этого документация выглядит как письмо Дяди Фёдора из Простоквашино:
Мои папа и мама! Я живу хорошо, просто замечательно. У меня все есть, есть свой дом, он теплый. В нем одна комната и кухня. Я без вас очень скучаю, особенно по вечерам. А здоровье мое не очень. То лапы ломит, то хвост отваливается.А на днях я линять начал. Старая шерсть с меня сыпется, хоть в дом не заходи. Зато новая растет чистая, шелковистая, так что лохматость у меня повысилась.До свидания, ваш сын, дядя Шарик.
Стайлгайд для технической документации: зачем нужен, из чего состоит, как его создавать