#какэтоработает
Всем привет! Сегодня поговорим об одном из самых популярных терминов в речи техписателей – docs-as-code.
Что такое docs-as-code?
🔆 Это подход к созданию документации, когда техписатели используют инструменты и практики разработки. По мнению documentat.io, docs-as-code подразумевает, что технические писатели выполняют хотя бы часть из указанных процессов:
– Пишут документацию в редакторах кода вроде VS Code и подобных.
– Используют языки разметки, например, Markdown или reStructureText.
– Хранят исходники в гите и используют его для совместной работы с файлами.
– Используют программные решения для “компиляции” документации – преобразования исходников в html-страницы. Такие инструменты называются SSG (Static Site Generator), чаще используется термин “генератор” или “сборщик”.
– Разворачивают документацию как приложения – с помощью так называемой технологии непрерывной интеграции и развёртывания (CI/CD).
Почему команды выбирают такое решение?
Аргументов “за” docs-as-code много. Рассмотрим три основных.
1️⃣ Первый, но не самый очевидный, – единый мир с продуктовой командой. Технические писатели, которые обычно отвечают за буквы и считаются гуманитариями, в этой парадигме полностью интегрируются в команду. Они неизбежно начинают разбираться в процессах разработки, лучше понимают разработчиков, а разработчики лучше понимают их.
2️⃣ Второй аргумент, самый веский – подход docs-as-code помогает создавать актуальную и полную документации за счёт самого процесса. Документация развивается и обновляется одновременно с продуктами.
3️⃣ Третий аргумент – гибкость решений и разгрузка команды, если используются генераторы. SSG, как правило, — это опенсорсные продукты с хорошей документацией и обширным сообществом. Благодаря этому технические писатели могут освоить инструмент самостоятельно и наладить сборку документации.
Если с инструментами разработки всё понятно, то что же значит “использовать практики разработки”? Об этом мы поговорим в следующем посте.
А пока давайте вспомним, какие же ещё плюсы у docs-as-code и какие недостатки?
Всем привет! Сегодня поговорим об одном из самых популярных терминов в речи техписателей – docs-as-code.
Что такое docs-as-code?
🔆 Это подход к созданию документации, когда техписатели используют инструменты и практики разработки. По мнению documentat.io, docs-as-code подразумевает, что технические писатели выполняют хотя бы часть из указанных процессов:
– Пишут документацию в редакторах кода вроде VS Code и подобных.
– Используют языки разметки, например, Markdown или reStructureText.
– Хранят исходники в гите и используют его для совместной работы с файлами.
– Используют программные решения для “компиляции” документации – преобразования исходников в html-страницы. Такие инструменты называются SSG (Static Site Generator), чаще используется термин “генератор” или “сборщик”.
– Разворачивают документацию как приложения – с помощью так называемой технологии непрерывной интеграции и развёртывания (CI/CD).
Почему команды выбирают такое решение?
Аргументов “за” docs-as-code много. Рассмотрим три основных.
1️⃣ Первый, но не самый очевидный, – единый мир с продуктовой командой. Технические писатели, которые обычно отвечают за буквы и считаются гуманитариями, в этой парадигме полностью интегрируются в команду. Они неизбежно начинают разбираться в процессах разработки, лучше понимают разработчиков, а разработчики лучше понимают их.
2️⃣ Второй аргумент, самый веский – подход docs-as-code помогает создавать актуальную и полную документации за счёт самого процесса. Документация развивается и обновляется одновременно с продуктами.
3️⃣ Третий аргумент – гибкость решений и разгрузка команды, если используются генераторы. SSG, как правило, — это опенсорсные продукты с хорошей документацией и обширным сообществом. Благодаря этому технические писатели могут освоить инструмент самостоятельно и наладить сборку документации.
Если с инструментами разработки всё понятно, то что же значит “использовать практики разработки”? Об этом мы поговорим в следующем посте.
А пока давайте вспомним, какие же ещё плюсы у docs-as-code и какие недостатки?
❤🔥31❤10🔥2
#какэтоработает
Всем привет! В прошлом посте мы поговорили о том, что же такое docs-as-code и почему команды выбирают именно его для создания документации.
Как создавать документацию с docs-as-code?
Допустим, мы уже переняли инструменты разработчиков: пишем документацию в markdown, используя VS Code, храним в гите, собираем генератором и поставляем в виде веб-ресурса. Но как использовать практики разработки?
Работа с документацией организована по аналогии с разработкой: одна функциональность – одна ветка в гите.
➕ Для каждой задачи, в которой предполагается обновление документации, создаётся отдельная ветка, в имя которой мы добавляем номер задачи.
➕ Для всего релиза тоже существует отдельная, релизная ветка, в которую мы сливаем все ветки-задачи, не удаляя исходные.
➕ Как только релиз сформирован у разработчиков, технический писатель уточняет, все ли задачи попали в релизную ветку документации. Если всё корректно, сливает ветку в основную.
❗️ Если по какой-то причине техписатель поспешил и залил в релизную ветку лишнюю задачу, некорректная релизная ветка удаляется и собирается новая из веток-задач, которые мы предусмотрительно не удаляем.
🔆 Готово. К релизу продукта мы получаем релизную ветку, в которой содержатся описания всех фичей и доработок.
Это только одна из возможных схем работы. Каждая команда выбирает удобный для себя путь.
Всем привет! В прошлом посте мы поговорили о том, что же такое docs-as-code и почему команды выбирают именно его для создания документации.
Как создавать документацию с docs-as-code?
Допустим, мы уже переняли инструменты разработчиков: пишем документацию в markdown, используя VS Code, храним в гите, собираем генератором и поставляем в виде веб-ресурса. Но как использовать практики разработки?
Работа с документацией организована по аналогии с разработкой: одна функциональность – одна ветка в гите.
❗️ Если по какой-то причине техписатель поспешил и залил в релизную ветку лишнюю задачу, некорректная релизная ветка удаляется и собирается новая из веток-задач, которые мы предусмотрительно не удаляем.
🔆 Готово. К релизу продукта мы получаем релизную ветку, в которой содержатся описания всех фичей и доработок.
Это только одна из возможных схем работы. Каждая команда выбирает удобный для себя путь.
Please open Telegram to view this post
VIEW IN TELEGRAM
👍18❤5🔥5
Всем привет!
В этот четверг, 3 октября, в 19:00 по московскому времени пройдёт митап для технических писателей, организованный коллегами из X5 Tech.
О чём пойдёт речь?
0️⃣ Лютикова Александра из X5 Tech расскажет, как выжить в режиме аврала.
0️⃣ Александр Мачулин из Gram.ax поделится опытом, как они пытались автоматизировать проверки по стайлгайдам.
0️⃣ Акимова Юлия из Яндекс Маркета расскажет, почему дизайнер, UX-редактор и исследователь — единый организм.
1️⃣ Круглый стол «UX-исследования справки и интерфейсов» с коллегами из X5, Cloud.ru, Авито, Яндекс Маркета и Ozon.
Митап будет онлайн и офлайн, а зарегистрироваться и узнать больше о встрече можно по ссылке.
#анонс
В этот четверг, 3 октября, в 19:00 по московскому времени пройдёт митап для технических писателей, организованный коллегами из X5 Tech.
О чём пойдёт речь?
Митап будет онлайн и офлайн, а зарегистрироваться и узнать больше о встрече можно по ссылке.
#анонс
Please open Telegram to view this post
VIEW IN TELEGRAM
x5-tech-event.timepad.ru
Techdoc Meetup #5 / События на TimePad.ru
Приглашаем вас на Techdoc Meetup #5, который пройдет 3 октября! Вас ждут 3 доклада: поговорим про работу в режиме аврала, автопроверки по внутренним гайдам и синергию UX-редактора со смежными ролями. По традиции завершит митап круглый стол, на этот раз об…
👍18❤5
#такбывает
Всем привет!
Иногда полезно делиться своими ошибками, даже самыми глупыми, чтобы больше никто их не совершал. А ещё такие истории помогают коллегам избавиться от синдрома самозванца — люди ошибаются, так бывает)
Самая полезная (нет) запись встречи
Для техписателя важно записывать все встречи. Какой бы ни была надёжной память, но в самый ответственный момент и она может подвести. Запись же позволяет сохранить информацию и лишний раз не беспокоить носителя знаний.
Поэтому я (Лида) и решила записать очередную встречу с разработчиком. Но по какой-то причине мой микрофон был программно отключен. И запись получилась такая:
Я: ...
Разработчик: Привет, давай.
Я: ...
Разработчик: Да, верно.
Я: ...
Разработчик: Да.
Я: ...
Разработчик: Да, сейчас это так работает.
Я: ...
Разработчик: Верно.
Я: ...
Разработчик: Хорошо, давай тогда договоримся - во вторник дедлайн.
*Конец записи*
Проверяйте настройки перед записью)
Всем привет!
Иногда полезно делиться своими ошибками, даже самыми глупыми, чтобы больше никто их не совершал. А ещё такие истории помогают коллегам избавиться от синдрома самозванца — люди ошибаются, так бывает)
Самая полезная (нет) запись встречи
Для техписателя важно записывать все встречи. Какой бы ни была надёжной память, но в самый ответственный момент и она может подвести. Запись же позволяет сохранить информацию и лишний раз не беспокоить носителя знаний.
Поэтому я (Лида) и решила записать очередную встречу с разработчиком. Но по какой-то причине мой микрофон был программно отключен. И запись получилась такая:
Я: ...
Разработчик: Привет, давай.
Я: ...
Разработчик: Да, верно.
Я: ...
Разработчик: Да.
Я: ...
Разработчик: Да, сейчас это так работает.
Я: ...
Разработчик: Верно.
Я: ...
Разработчик: Хорошо, давай тогда договоримся - во вторник дедлайн.
*Конец записи*
Проверяйте настройки перед записью)
😁50😢24👏9👍7🤝3
#колонкаредактора
Всем привет! Продолжаем разговор об особенностях профессии. И сегодня наша тема:
Трамплин в IT или профессия?
Да, действительно, очень часто профессия технического писателя преподносится именно как лёгкий способ присоединиться к IT-сообществу. К техписателю не предъявляются такие требования, как, например, к разработчику или тестировщику: просто пиши и пиши себе текст.
И отчасти это так: знания языков программирования от техписателей требуют не везде.
😎 - Вот освою техписательство и уйду в разработчики!
Но есть ли границы у навыков технического писателя? Можно ли в какой-то момент времени сказать, что "освоил техписательство"?
Для удобства разделим навыки технического писателя на группы.
1️⃣ Язык
В командах техписатели становятся точкой истины в любых языковых вопросах. Как написать слово, фразу, нужна ли запятая — на все эти вопросы вы должны быть готовы ответить. Качественно перестроить структуру всей документации или сам текст тоже нужно уметь.
Вашим пользователям всё понятно? Документация помогает использовать продукт? Все процессы доступно зафиксированы? Отлично!
2️⃣ Инструменты
Документация не витает в воздухе — команды передают её заказчику в каком-то виде. Например, в виде страниц в корпоративной вики или в виде распечатанных страниц Word.
Можете ли вы одним махом форматировать все таблицы на 300 страницах текста? Сами создаёте макросы? А может ещё и схемы чертите? Супер!
3️⃣ Управление
Никто лучше технического писателя не знает, как эффективнее рассказать о продукте. Возможно, стоит прекратить передавать бумажки и предложить заказчикам веб-портал, да и вообще нанять ещё одного техписателя, ведь и команда, и продукт давно выросли.
Вы можете выстроить стратегию документации, рассчитать трудозатраты на её реализацию и разработать подробный план? Великолепно!
🧐 - Уже всё? Уже можно уходить в разработчики?
Мы ответим, что уйти можно в любой момент, и вы уйдёте, так и не узнав... Что это ещё не всё)
4️⃣ DocOps
Целый пласт навыков на стыке техписательства, фронтенд-, бэкенд-разработки и DevOps.
5️⃣ Локализация и интернационализация
Мастерство адаптации документации для другой страны или целого мира. Да-а, это всё ещё возможно) Подробнее об этих направлениях напишем в отдельных постах.
😏 — Оу, здесь уже и платят неплохо, и код писать могу, и зачем мне тогда в разработчики?
Техписатель — не просто трамплин в IT, а самая настоящая профессия. И, если для вас это важно, у неё есть свой госстандарт. Оставайтесь с нами❤️
Всем привет! Продолжаем разговор об особенностях профессии. И сегодня наша тема:
Трамплин в IT или профессия?
Да, действительно, очень часто профессия технического писателя преподносится именно как лёгкий способ присоединиться к IT-сообществу. К техписателю не предъявляются такие требования, как, например, к разработчику или тестировщику: просто пиши и пиши себе текст.
И отчасти это так: знания языков программирования от техписателей требуют не везде.
😎 - Вот освою техписательство и уйду в разработчики!
Но есть ли границы у навыков технического писателя? Можно ли в какой-то момент времени сказать, что "освоил техписательство"?
Для удобства разделим навыки технического писателя на группы.
1️⃣ Язык
В командах техписатели становятся точкой истины в любых языковых вопросах. Как написать слово, фразу, нужна ли запятая — на все эти вопросы вы должны быть готовы ответить. Качественно перестроить структуру всей документации или сам текст тоже нужно уметь.
Вашим пользователям всё понятно? Документация помогает использовать продукт? Все процессы доступно зафиксированы? Отлично!
2️⃣ Инструменты
Документация не витает в воздухе — команды передают её заказчику в каком-то виде. Например, в виде страниц в корпоративной вики или в виде распечатанных страниц Word.
Можете ли вы одним махом форматировать все таблицы на 300 страницах текста? Сами создаёте макросы? А может ещё и схемы чертите? Супер!
3️⃣ Управление
Никто лучше технического писателя не знает, как эффективнее рассказать о продукте. Возможно, стоит прекратить передавать бумажки и предложить заказчикам веб-портал, да и вообще нанять ещё одного техписателя, ведь и команда, и продукт давно выросли.
Вы можете выстроить стратегию документации, рассчитать трудозатраты на её реализацию и разработать подробный план? Великолепно!
🧐 - Уже всё? Уже можно уходить в разработчики?
Мы ответим, что уйти можно в любой момент, и вы уйдёте, так и не узнав... Что это ещё не всё)
4️⃣ DocOps
Целый пласт навыков на стыке техписательства, фронтенд-, бэкенд-разработки и DevOps.
5️⃣ Локализация и интернационализация
Мастерство адаптации документации для другой страны или целого мира. Да-а, это всё ещё возможно) Подробнее об этих направлениях напишем в отдельных постах.
Техписатель — не просто трамплин в IT, а самая настоящая профессия. И, если для вас это важно, у неё есть свой госстандарт. Оставайтесь с нами❤️
Please open Telegram to view this post
VIEW IN TELEGRAM
❤30🔥9👌4🤝1
А вы в техническом писательстве временно или надолго?
Anonymous Poll
12%
Я на трамплине
68%
Я техписатель
19%
Мне только посмотреть😊
❤4🔥3🥰2👍1💯1
#колонкаредактора
Всем привет! "Где учиться на техписателя?" — самый частый вопрос от новичков. Это важный вопрос, но мы предлагаем начать с другого: как учиться на техписателя?
Самообразование, курсы, менторы — три уровня образования
Почему мы рекомендуем выстроить обучение именно так? Рассказываем.
1️⃣ Самообразование
Новички всегда в поисках курсов. Кажется, что появится школа, которая всему научит. Но техническая документация — очень широкое понятие. Ни одни курсы не принесут вам пользы, если не знать, что именно вы хотите изучить.
Поэтому, прежде чем искать курсы, мы советуем поучиться самостоятельно. Это позволит вам точно понимать, что искать дальше.
Всем новичкам мы предлагаем:
*️⃣ Посмотреть курс на ютуб от Документата,
*️⃣ Почитать редполитики, например, редполитику Госуслуг,
*️⃣ Почитать книгу Кагарлицкого (ссылку дали как пример, что-то цена там неконкурентная),
*️⃣ Подписаться на нас и почитать посты с начала 😊
2️⃣ Курсы
Курсы, которые испытаны нами лично, посоветовать не получится, потому что они не вынесли испытание временем, хотя были очень хороши.
Есть курсы, которые предлагают трудоустройство лучшим своим ученикам. В любом случае, успешные домашние задания на курсах позже можно будет показать в качестве примеров работ.
В выборе курсов вы можете положиться на рекомендации коллег, либо и вовсе пропустить этот шаг и продолжить обучаться самостоятельно с помощью доступных каналов и публикаций или с помощью ментора.
3️⃣ Менторы
Кто такие менторы? Это опытные технические писатели, которые за деньги (от 2 000 рублей за час) помогут вам решить конкретные задачи в обучении. Например, они могут выстроить индивидуальный план обучения, исходя их ваших знаний, либо поделиться знаниями в конкретной области.
Некоторые менторы могут помочь вам в устройстве на работу: например, порекомендовать вас своим знакомым-нанимателям. Но вы должны понимать, что рекомендаций мало и вы сами должны суметь пройти отбор.
И тут мы снова возвращаемся к пункту 1😉
Самообразование — основа всего обучения.
🔆 Если вы уже прошли какой-то хороший курс или нашли хорошую публикацию, поделитесь, пожалуйста, ссылкой на них в комментариях.
Также вы можете оставить ссылку на свой канал или курс, если они посвящены технической документации.
Давайте соберем для новичков полезную информацию.
Всем привет! "Где учиться на техписателя?" — самый частый вопрос от новичков. Это важный вопрос, но мы предлагаем начать с другого: как учиться на техписателя?
Самообразование, курсы, менторы — три уровня образования
Почему мы рекомендуем выстроить обучение именно так? Рассказываем.
1️⃣ Самообразование
Новички всегда в поисках курсов. Кажется, что появится школа, которая всему научит. Но техническая документация — очень широкое понятие. Ни одни курсы не принесут вам пользы, если не знать, что именно вы хотите изучить.
Поэтому, прежде чем искать курсы, мы советуем поучиться самостоятельно. Это позволит вам точно понимать, что искать дальше.
Всем новичкам мы предлагаем:
2️⃣ Курсы
Курсы, которые испытаны нами лично, посоветовать не получится, потому что они не вынесли испытание временем, хотя были очень хороши.
Есть курсы, которые предлагают трудоустройство лучшим своим ученикам. В любом случае, успешные домашние задания на курсах позже можно будет показать в качестве примеров работ.
В выборе курсов вы можете положиться на рекомендации коллег, либо и вовсе пропустить этот шаг и продолжить обучаться самостоятельно с помощью доступных каналов и публикаций или с помощью ментора.
3️⃣ Менторы
Кто такие менторы? Это опытные технические писатели, которые за деньги (от 2 000 рублей за час) помогут вам решить конкретные задачи в обучении. Например, они могут выстроить индивидуальный план обучения, исходя их ваших знаний, либо поделиться знаниями в конкретной области.
Некоторые менторы могут помочь вам в устройстве на работу: например, порекомендовать вас своим знакомым-нанимателям. Но вы должны понимать, что рекомендаций мало и вы сами должны суметь пройти отбор.
И тут мы снова возвращаемся к пункту 1
Самообразование — основа всего обучения.
🔆 Если вы уже прошли какой-то хороший курс или нашли хорошую публикацию, поделитесь, пожалуйста, ссылкой на них в комментариях.
Также вы можете оставить ссылку на свой канал или курс, если они посвящены технической документации.
Давайте соберем для новичков полезную информацию.
Please open Telegram to view this post
VIEW IN TELEGRAM
❤28✍3🤓3👍2🤷1
#писалитирекомендует
Всем привет!
И в том числе привет всем новеньким подписчикам❤️
Мы решили помочь вам выжать максимум из нашего канала. Будем публиковать дайджесты с ранними постами, которые могут быть интересны в свете обсуждений в сообществе, например, в жёлтом чате.
Итак, популярная тема на этой неделе — грейды техписателей.
У нас по этой теме:
1️⃣ Грейды технических писателей: примерная лестница для новичков и бесплатная основа для вашего ранжирования. Забирайте и подстраивайте под себя)
2️⃣ Чем сеньор отличается от джуна? Размышления у парадного подъезда)
3️⃣ Что делать джуну, если лид ушёл в отпуск? Наши рекомендации, или чего мы ждали от своих джунов
Учитесь вместе с нами❤️
Всем привет!
И в том числе привет всем новеньким подписчикам❤️
Мы решили помочь вам выжать максимум из нашего канала. Будем публиковать дайджесты с ранними постами, которые могут быть интересны в свете обсуждений в сообществе, например, в жёлтом чате.
Итак, популярная тема на этой неделе — грейды техписателей.
У нас по этой теме:
Учитесь вместе с нами❤️
Please open Telegram to view this post
VIEW IN TELEGRAM
👍20❤13
Всем привет!
Сегодня, 14 ноября, в 19:00 по московскому времени пройдёт митап для технических писателей, организованный коллегами из Cloud․ru.
О чём пойдёт речь?
🔴 Юлия Служаева из Cloud․ru расскажет о редполитике: как написать правила и не устроить бои без правил.
🔵 Марина Смирнова и Екатерина Каляева из Cloud․ru поделятся, как они автоматизировали проверку документации: кейс с линтером Vale.
🟢 Антон Литвинов из SberDevices поговорит о системе метрик клиентской документации.
🟠 Теодора Малевинская из T-Bank расскажет о частых ошибках техписателей в поиске работы.
Ссылка на онлайн-трансляцию появится в канале TeamSnack TechWriters, не пропустите :)
#анонс
Сегодня, 14 ноября, в 19:00 по московскому времени пройдёт митап для технических писателей, организованный коллегами из Cloud․ru.
О чём пойдёт речь?
Ссылка на онлайн-трансляцию появится в канале TeamSnack TechWriters, не пропустите :)
#анонс
Please open Telegram to view this post
VIEW IN TELEGRAM
Telegram
TeamSnack TechWriters Channel
Неформальный канал технических писателей Cloud.ru об инструментах, методологии, технологиях, мемах и профессиональном развитии
❤16✍8