Size: a a a

technicalwriters

2020 November 10

СФ

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

L

Lana in technicalwriters
Ekaterina Noskova
привет. у нас есть какие-нибудь стандарты индустрии в документировании? например, используется docs-as-code, есть стайлгайд, процессы автоматизированы по максимуму (создание, публикация, тестирование, локализация), Swagger как спека для API документации и т.д.
ты имеешь в виду вроде стандартов ISO или именно какие-то наши разделяемые конвенции внутренние?
источник

FM

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

E

Evgeniia in technicalwriters
Fox Mulder
А как вы относитесь к вставке видео в html-документацию?
положительно ) вставляем иногда ролики, которые выкладываем на ютуб
источник

FM

Fox Mulder in technicalwriters
Evgeniia
положительно ) вставляем иногда ролики, которые выкладываем на ютуб
Я тут у одной компании подсмотрел. Там, в видео, объяснялась архитектура продукта и базово как поднять веб-сервер. Выглядело неплохо.
источник

EN

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

E

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

L

Lana in technicalwriters
Ekaterina Noskova
если с разработкой аналогию провести, то например стандартом индустрии сейчас является git. есть ли такое в документировании? чтобы можно было посмотреть на документацию и сказать: она соответствует стандартам индустрии. не знаю, описано ли это в ISO
если прям стандарт для сертификации, то ICS 01.110. git мне не кажется стандартом, это система контроля версий, а вот например git flow и подходы к ведению веток - это уже больше смахивает на стандарт или там Python Styleguide например, я бы такого рода аналоги искала
источник

L

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

FM

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

L

Lana in technicalwriters
Fox Mulder
Лана, а зачем стек на метрики техписам?
я про разработку
источник

СФ

Семён Факторович... in technicalwriters
Lana
если прям стандарт для сертификации, то ICS 01.110. git мне не кажется стандартом, это система контроля версий, а вот например git flow и подходы к ведению веток - это уже больше смахивает на стандарт или там Python Styleguide например, я бы такого рода аналоги искала
first и foremost technologies, кажется, не совсем про нас — все-таки у каждой команды плюс-минус свой стек: у кого-то выстраданные локальными требованиями узкоспециальные SSG, у кого-то Help&Manual, у кого-то только Confluence

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

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

ET

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

MC

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

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

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

L

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

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

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

L

Lana in technicalwriters
краудсорсно
источник

ДС

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

NV

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

L

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

NV

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