В своем докладе я упомянул, что с помощью Foliant и Slate также можно документировать и gRPС API (на слайдах этого нет).
Исправляю ситуацию (для тех, кто спрашивал про это после доклада).
Вот ссылка на тулзу proto2slate, которая конвертирует файлы .proto в Markdown.
Полученный Markdown скармливаем Слэйту и получаем справочник API.
На скринах — фрагмент содержимого файла .proto и скрин сайта, который из этого получается.
Исправляю ситуацию (для тех, кто спрашивал про это после доклада).
Вот ссылка на тулзу proto2slate, которая конвертирует файлы .proto в Markdown.
Полученный Markdown скармливаем Слэйту и получаем справочник API.
На скринах — фрагмент содержимого файла .proto и скрин сайта, который из этого получается.
🔥5🤝2✍1
Потренироваться в работе с консолью, небоясь ничего сломать
Техпис, держи сервис «Теминатор», который БЕСПЛАТНО дает возможность потренироваться в работе с консолью (терминалом). Здесь ты прямо в браузере можешь работать с терминалом.
Плюсы: можно делать все, что угодно (но главное на перестараться, а то вдруг еще IP заблокируют).
Минус: время одной сессии ограничено 15 минутами.
Техпис, держи сервис «Теминатор», который БЕСПЛАТНО дает возможность потренироваться в работе с консолью (терминалом). Здесь ты прямо в браузере можешь работать с терминалом.
Плюсы: можно делать все, что угодно (но главное на перестараться, а то вдруг еще IP заблокируют).
Минус: время одной сессии ограничено 15 минутами.
🔥8✍4👍2
Про фэйлы при работе с текстами
Наверняка у каждого, кто работает с текстами, случались фэйлы, которые «уезжали на прод».
У меня такое было.
Самый яркий фэйл случился в 2012 году, когда я слепил для себя сайт, чтобы привлекать клиентов на копирайтинг. Сделал сайт, а в подвале разместил «Агенство копирайтинга»(без буквы т) . Благо, не на всех страницах так было (сайт делал вручную в Macromedia Dreamwiever, шаблоны не использовал: только кропотливый ручной труд 😀).
И висело все это добро в интернете несколько месяцев. Заметил я фэйл просто случайно: стыдно было, очень стыдно.
К слову, клиенты все равно приходили. Даже банк один удалось привлечь: писал им тексты для проекта по платежным терминалам.
Так что, вычитывайте свои тексты, чтобы не было обидных фэйлов.А я до сих пор не очень-то люблю вычитывать свои же тексты.
Наверняка у каждого, кто работает с текстами, случались фэйлы, которые «уезжали на прод».
У меня такое было.
Самый яркий фэйл случился в 2012 году, когда я слепил для себя сайт, чтобы привлекать клиентов на копирайтинг. Сделал сайт, а в подвале разместил «Агенство копирайтинга»
И висело все это добро в интернете несколько месяцев. Заметил я фэйл просто случайно: стыдно было, очень стыдно.
К слову, клиенты все равно приходили. Даже банк один удалось привлечь: писал им тексты для проекта по платежным терминалам.
Так что, вычитывайте свои тексты, чтобы не было обидных фэйлов.
❤5👍3👎1🔥1
Прежде чем в доку код добавлять
Нужно его сквозь форматтер прогнать
Сегодня кучу времени потратил на правку примеров кода (примеры использования DSL) в доке для in-memory базы данных, за которую я отвечаю. А все почему? Да потому, что в начале работы над документацией я добавлял туда примеры, копируя их прямо из Postman (позже все-таки стал прогонять через форматтер). А он, собака, добавляет лишних пробелов, из-за чего код может выглядеть не очень красиво.
В итоге — более 60 правок в 22 файлах. А ведь это время можно было потратить с куда большей пользой 🙃
Чтобы не быть как я, пользуйтесь форматтерами, которые красиво форматируют код, и он гарантированно смотрится в доке красиво.
Чем пользоваться? Категорически рекомендую онлайн сервис jsonformatter.org. И ничего, что в названии у него «json». Сервис отлично форматирует куски кода на разных языках (см. скрин).
Кроме форматтера здесь есть и другие полезные функции. Например, этот сервис может превратить JSON-объект в код на Go или Java, в котором формируется соответствующая этому объекту структура. Я эту функцию использовал при тестировании Go-коннектора для подключения к той самой in-memory базе данных.
Нужно его сквозь форматтер прогнать
Сегодня кучу времени потратил на правку примеров кода (примеры использования DSL) в доке для in-memory базы данных, за которую я отвечаю. А все почему? Да потому, что в начале работы над документацией я добавлял туда примеры, копируя их прямо из Postman (позже все-таки стал прогонять через форматтер). А он, собака, добавляет лишних пробелов, из-за чего код может выглядеть не очень красиво.
В итоге — более 60 правок в 22 файлах. А ведь это время можно было потратить с куда большей пользой 🙃
Чтобы не быть как я, пользуйтесь форматтерами, которые красиво форматируют код, и он гарантированно смотрится в доке красиво.
Чем пользоваться? Категорически рекомендую онлайн сервис jsonformatter.org. И ничего, что в названии у него «json». Сервис отлично форматирует куски кода на разных языках (см. скрин).
Кроме форматтера здесь есть и другие полезные функции. Например, этот сервис может превратить JSON-объект в код на Go или Java, в котором формируется соответствующая этому объекту структура. Я эту функцию использовал при тестировании Go-коннектора для подключения к той самой in-memory базе данных.
👍7👎1🔥1🤝1
Отличная новость.
А у меня уже есь тема и тезисы для доклада (еще на TechWriter Days #1 придумал).
Но заявку уже подам в режиме «давайте после майских».
А у меня уже есь тема и тезисы для доклада (еще на TechWriter Days #1 придумал).
Но заявку уже подам в режиме «давайте после майских».
👍4❤🔥2🔥2
Forwarded from Vladislav Orlikov (Belarus)
📣 Уважаемые коллеги!
Открыта регистрация и прием докладов на TechWriter Days #2.
https://techwriterdays.ru/ru/index
Конференция пройдет 28-29 марта 2025 г. в Санкт-Петербурге (отель Airportcity Plaza, ул. Стартовая 6, лит. А)
Внимание! Прием докладов будет производится до 31 июля включительно.
Открыта регистрация и прием докладов на TechWriter Days #2.
https://techwriterdays.ru/ru/index
Конференция пройдет 28-29 марта 2025 г. в Санкт-Петербурге (отель Airportcity Plaza, ул. Стартовая 6, лит. А)
Внимание! Прием докладов будет производится до 31 июля включительно.
Из копирайтерского: Работать по 3 часа в день и зарабатывать на текстах 100 000+? Кажется, это реально
Со времен фриланса оставил я себе одного постоянного клиента, чтобы не терять навыков и быть в курсе, что вообще в нише «текстовиков» происходит. Пишу для него в свободное от работы время несложные, относительно небольшие IT-тексты (по 2000 симв. без пробелов) для SEO, по 800 рублей за штуку.
Уже продолжительное время привлекаю к этому ИИ🤖 . Естественно, вопрос этот с заказчиком я заранее согласовал, с условием, что цену на услуги я чуть-чуть снижу (до этого один такой текст обходился ему дороже 800 рублей). Он согласился на такой эксперимент. Сейчас могу с увереность сказать, что, ему все нравится, и площадки тексты без проблем принимают.
Тексты получается писать довольно быстро. На каждый уходит всего 20 минут (а иногда и меньше). Процесс выглядит так:
1️⃣ Даю ИИ несколько промптов в последовательности, соответствующей структуре будущей статьи.
2️⃣ Копирую их в один документ.
3️⃣ Редактирую. Редактирование текстов от ИИ — это отдельная тема, со своими нюансами и заморочками. Впрочем, как и составление правильных промптов и их отправка в нужной последовательности (со временем рука набивается).
Итого за 20 минут можно заработать 800 рублей. Подобных текстов моему заказчику нужно много, т.к. в работе у него несколько клиентских проектов. Но, т.к. я работаю на фуллтайме, не беру много: рассчитываю нагрузку так, чтобы это было не в ущерб свободному времени и основной работе (фриланс в рабочее время — это не про меня).
Так вот. В интернете куча предложений научить всех желающих успешному успеху в стиле «Работай под пальмой по 3 часа в день и зарабатывай 100 000+». Я к ним отношусь негативно. А может зря? Ведь с появлением ИИ это выглядит вполне реальным. Возьмем, например, 20 минут на текст, который стоит 800 рублей… Путем несложных расчетов можно понять, сколько нужно работать копирайтеру в день, чтобы зарабатывать те самые 100 000+ (даже меньше трех часов при 20 рабочих днях в месяце).
К слову, у меня куда больше времени уходило на редактуру текстов от живых авторов,когда я «барыжил» текстами, перепродавая их на биржах (да, был у меня и такой бесценный опыт). При этом выхлоп был меньше.
Конечно, чтобы найти заказчика на такой поток текстов, нужно постараться (но это реально, т.к. SEO, которое уже лет❓ дцать хоронят, пока еще живее всех живых). Да и в теме, на которую пишешь, нужно «шурупить», т.к. тексты от ИИ требуют от проверяющего прям 80 lvl умения в фактчекинг.
Но, в общем и целом, это реально. Есть над чем задуматься.Некоторым кожаным мешкам стоит напрячься :).
Что скажете?
Со времен фриланса оставил я себе одного постоянного клиента, чтобы не терять навыков и быть в курсе, что вообще в нише «текстовиков» происходит. Пишу для него в свободное от работы время несложные, относительно небольшие IT-тексты (по 2000 симв. без пробелов) для SEO, по 800 рублей за штуку.
Уже продолжительное время привлекаю к этому ИИ
Тексты получается писать довольно быстро. На каждый уходит всего 20 минут (а иногда и меньше). Процесс выглядит так:
1️⃣ Даю ИИ несколько промптов в последовательности, соответствующей структуре будущей статьи.
2️⃣ Копирую их в один документ.
3️⃣ Редактирую. Редактирование текстов от ИИ — это отдельная тема, со своими нюансами и заморочками. Впрочем, как и составление правильных промптов и их отправка в нужной последовательности (со временем рука набивается).
Итого за 20 минут можно заработать 800 рублей. Подобных текстов моему заказчику нужно много, т.к. в работе у него несколько клиентских проектов. Но, т.к. я работаю на фуллтайме, не беру много: рассчитываю нагрузку так, чтобы это было не в ущерб свободному времени и основной работе (фриланс в рабочее время — это не про меня).
Так вот. В интернете куча предложений научить всех желающих успешному успеху в стиле «Работай под пальмой по 3 часа в день и зарабатывай 100 000+». Я к ним отношусь негативно. А может зря? Ведь с появлением ИИ это выглядит вполне реальным. Возьмем, например, 20 минут на текст, который стоит 800 рублей… Путем несложных расчетов можно понять, сколько нужно работать копирайтеру в день, чтобы зарабатывать те самые 100 000+ (даже меньше трех часов при 20 рабочих днях в месяце).
К слову, у меня куда больше времени уходило на редактуру текстов от живых авторов,
Конечно, чтобы найти заказчика на такой поток текстов, нужно постараться (но это реально, т.к. SEO, которое уже лет
Но, в общем и целом, это реально. Есть над чем задуматься.
Что скажете?
Please open Telegram to view this post
VIEW IN TELEGRAM
❤🔥3🔥3👾3
Как изобразить мэппинг (маппинг, mapping) данных в разных системах (источниках)
В этом посте под мэппингом понимается это соотношение между данными, которые находятся в разных системах.
Как техпису описать мэппинг данных? Хороший и понятный большинству способ — отобразить процесс визуально.
На скрине — простой пример, как это может выглядеть.
Согласитесь, здесь все предельно понятно: что откуда берется в одной системе и куда сохраняется в другой, как при этом преобразуются данные (если есть преобразование).
А какими инструментами можно это делать?
Вариантов масса. Хочешь — рисуй руками. А хочешь — кодом. Мне ближе второй вариант. Про него расскажу в одном из следующих постов.
В этом посте под мэппингом понимается это соотношение между данными, которые находятся в разных системах.
Как техпису описать мэппинг данных? Хороший и понятный большинству способ — отобразить процесс визуально.
На скрине — простой пример, как это может выглядеть.
Согласитесь, здесь все предельно понятно: что откуда берется в одной системе и куда сохраняется в другой, как при этом преобразуются данные (если есть преобразование).
А какими инструментами можно это делать?
Вариантов масса. Хочешь — рисуй руками. А хочешь — кодом. Мне ближе второй вариант. Про него расскажу в одном из следующих постов.
👍6🔥4
НЛО прилетело, приглашение принесло
Решил я на днях побороть вселенскую несправедливость и стать автором на Хабре.
Не порядок ведь: писал на Хабр не раз, но было это всё для клиентов, а публикаций от своего имени не было (хотя зарегался там в 2016 году).
И вот свершилось. Пару дней дней назад добавил на Хабр статью по материалам моего доклада на TW Days#1, а сегодня после обеда ее выпустили из песочницы.
Вот, собственно, статья.
Теперь я официально «Захабренный» (только бы не заминусовали новичка ).
Решил я на днях побороть вселенскую несправедливость и стать автором на Хабре.
Не порядок ведь: писал на Хабр не раз, но было это всё для клиентов, а публикаций от своего имени не было (хотя зарегался там в 2016 году).
И вот свершилось. Пару дней дней назад добавил на Хабр статью по материалам моего доклада на TW Days#1, а сегодня после обеда ее выпустили из песочницы.
Вот, собственно, статья.
Теперь я официально «Захабренный» (
Хабр
Документирование HTTP API (и не только) с Foliant
Привет, Хабр. В статье расскажу про Foliant и про возможности по документированию HTTP API с его использованием. Упор сделаю на API, которые описываются с помощью OpenAPI/Swagger. Также вскользь...
🔥15❤3😁1
Регулярки можно изображать в виде схем
И делается все без особых напрягов.
Вы знали об этом? Я — нет. И только недавно узнал.
А ведь очень удобно.
И готовый инструмент для такой задачи есть. Это — PlantUML.
Скармливаем ему регулярное выражение и получаем вполне себе понятую и удобоваримую схему.
Пример кода для схематического представления регулярки для проверки номера телефона, взятой отсюда (номер 3 в списке):
Результат — на картинке.
Согласитесь, довольно удобно и просто читать такую схему.
И делается все без особых напрягов.
Вы знали об этом? Я — нет. И только недавно узнал.
А ведь очень удобно.
И готовый инструмент для такой задачи есть. Это — PlantUML.
Скармливаем ему регулярное выражение и получаем вполне себе понятую и удобоваримую схему.
Пример кода для схематического представления регулярки для проверки номера телефона, взятой отсюда (номер 3 в списке):
@startregex
title RegExp для проверки номера телефона
/^\+?(\d{1,3})?[- .]?\(?(?:\d{2,3})\)?[- .]?\d\d\d[- .]?\d\d\d\d$/
@endregex
Результат — на картинке.
Согласитесь, довольно удобно и просто читать такую схему.
❤6🔥5
Про мутации (нет, это не из постапокалиптических фильмов, а из API)
Доводилось ли вам слышать про мутации?
В контексте техписательства (и не только) мутация — это тип операции в GraphQL API, с помощью которой меняются данные на сервере: добавляются, изменяются и удаляются.
Если в HTTP API (или REST, с вашего позволения) используется четыре разных типа запроса (имеется ввиду их разделение по используемому HTTP-глаголу):
-
-
-
-
то в GraphQL для этого всего есть один тип операции
А как тогда определять, что делает та или иная мутация, создает что-то, изменяет или удаляет? Нейминг!!! Важно при проектировании GraphQL API (впрочем, как и проектировании любого другого API) называть операции понятными именами.
Например:
•
•
•
Ну и прикрепляю картинку: так искусственный интеллект видит изображение на тему «Использование мутаций в GraphQL API».
Доводилось ли вам слышать про мутации?
В контексте техписательства (и не только) мутация — это тип операции в GraphQL API, с помощью которой меняются данные на сервере: добавляются, изменяются и удаляются.
Если в HTTP API (или REST, с вашего позволения) используется четыре разных типа запроса (имеется ввиду их разделение по используемому HTTP-глаголу):
-
POST
,-
PUT
,-
PATCH
,-
DELETE
.то в GraphQL для этого всего есть один тип операции
Mutation
.А как тогда определять, что делает та или иная мутация, создает что-то, изменяет или удаляет? Нейминг!!! Важно при проектировании GraphQL API (впрочем, как и проектировании любого другого API) называть операции понятными именами.
Например:
•
createUser
— понятно, что мутация будет создавать пользователя.•
updateProduct
— очевидно, что такая мутация обновляет сведения о продукте.•
deleteFilm
— видно, что мутация удаляет фильм.Ну и прикрепляю картинку: так искусственный интеллект видит изображение на тему «Использование мутаций в GraphQL API».
❤7👌2
IKIWISI: техписы тоже с этим встречаются
Есть у аналитиков аббревиатура IKIWISI, образованная от фразы, которую многие просто ненавидят. Это фраза «I’ll know it when I see it», что переводится как «Узнаю, когда увижу».
Обычно такое слышишь от заказчика, который толком не знает, чего он хочет: типа «Ты что-нибудь сделай, а том посмотрим, то ли это, что я хочу».
У техписов тоже такое случается частенько: приходит заказчик, просит сделать какой-то документ, но объяснить, что в нем должно быть, и как это должно выглядеть, не может. Так что, аббревиатура IKIWISI и нелюбовь к ней, я считаю, к техническим писателям тоже применимы. Ну и IKIWISI — это «родня» фразы «Без нормального ТЗ результат будет ХЗ».
Что скажете?
Есть у аналитиков аббревиатура IKIWISI, образованная от фразы, которую многие просто ненавидят. Это фраза «I’ll know it when I see it», что переводится как «Узнаю, когда увижу».
Обычно такое слышишь от заказчика, который толком не знает, чего он хочет: типа «Ты что-нибудь сделай, а том посмотрим, то ли это, что я хочу».
У техписов тоже такое случается частенько: приходит заказчик, просит сделать какой-то документ, но объяснить, что в нем должно быть, и как это должно выглядеть, не может. Так что, аббревиатура IKIWISI и нелюбовь к ней, я считаю, к техническим писателям тоже применимы. Ну и IKIWISI — это «родня» фразы «Без нормального ТЗ результат будет ХЗ».
Что скажете?
🤝13❤5
Умели же когда-то обложки привлекательные для книг делать
Разбирал вчера свои книжные запасы и нашел эту книгу из 2013 года.
Кстати, книга просто офигенская. После нее я вкатился в написание экспертных статей для SEO-специалистов и интернет-маркетологов. Сейчас, конечно, SEO другое, но основы основ из этой книги можно почерпнуть.
Разбирал вчера свои книжные запасы и нашел эту книгу из 2013 года.
Кстати, книга просто офигенская. После нее я вкатился в написание экспертных статей для SEO-специалистов и интернет-маркетологов. Сейчас, конечно, SEO другое, но основы основ из этой книги можно почерпнуть.
🔥6😁5
Ура!!! Я только что защитил дипломный проект!!!
8 месяцев обучения пролетели незаметно. И было это продуктивно.
Теперь я не только технический писатель, но иподробности позже .
8 месяцев обучения пролетели незаметно. И было это продуктивно.
Теперь я не только технический писатель, но и
🔥12🏆9👍2👏1
Техпис не должен... Или рынок все порешает
Наверное, это холиварная тем, но все-таки.
Что-то в последнее время все чаще стали попадаться высказывания типа «Техпис не должен...». Как правило, они всплывают в обсуждениях вакансий.
У большего количества таких высказываний посыл такой: мол техпис не должен делать ничего, кроме как писать инструкции.
Они говорят, что техпис не должен:
- описывать архитектуру,
- участвовать в написании спецификаций,
- лезть в код и разбираться с тем, чего там понаписали разработчики,
- настраивать пайплайны сборки документации,
- рисовать диаграммы за аналитиков и архитекторов....
А вот я так не считаю. Я думаю, что техпис должен. Должен стремиться к тому, чтобы пощупать всё, попробовать всё, понабивать шишки обо всё.
Должен, но с оговоркой: если работодатель достойно за это платит (достойная оплата — это тема для отдельного разговора).
Почему техпис должен? Я считаю, что это полезно для него же в первую очередь. Я уверен, что востребованный на рынке технический писатель — это T-shape специалист. А как стать таким специалистом, если ты свято веришь в «Техпис не должен»?
Водитель фуры, например тоже не должен менять колесо (для этого есть специальные бригады). Но большинство дальнобойщиков не ждет, пока к ним приедет эта самая бригада. Они берут и делают все самостоятельно.
Разработчики, по-хорошему, не должны настраивать CI/CD для своих продуктов (есть же девопсы под это дело). Но знаю, что многие сами это делают.
Да, может быть, в идеальном мире технический писатель реально не должен ничего, кроме как сидеть в уголочке и тихонько писать свои инструкции. Но живем мы в мире реальном. И я считаю, что техпис еще много чего должен (при условии получения соответствующего поощрения от работодателя). А за тех, кто «не должен» рынок все сам порешает.
Что скажете?
Наверное, это холиварная тем, но все-таки.
Что-то в последнее время все чаще стали попадаться высказывания типа «Техпис не должен...». Как правило, они всплывают в обсуждениях вакансий.
У большего количества таких высказываний посыл такой: мол техпис не должен делать ничего, кроме как писать инструкции.
Они говорят, что техпис не должен:
- описывать архитектуру,
- участвовать в написании спецификаций,
- лезть в код и разбираться с тем, чего там понаписали разработчики,
- настраивать пайплайны сборки документации,
- рисовать диаграммы за аналитиков и архитекторов....
А вот я так не считаю. Я думаю, что техпис должен. Должен стремиться к тому, чтобы пощупать всё, попробовать всё, понабивать шишки обо всё.
Должен, но с оговоркой: если работодатель достойно за это платит (достойная оплата — это тема для отдельного разговора).
Почему техпис должен? Я считаю, что это полезно для него же в первую очередь. Я уверен, что востребованный на рынке технический писатель — это T-shape специалист. А как стать таким специалистом, если ты свято веришь в «Техпис не должен»?
Водитель фуры, например тоже не должен менять колесо (для этого есть специальные бригады). Но большинство дальнобойщиков не ждет, пока к ним приедет эта самая бригада. Они берут и делают все самостоятельно.
Разработчики, по-хорошему, не должны настраивать CI/CD для своих продуктов (есть же девопсы под это дело). Но знаю, что многие сами это делают.
Да, может быть, в идеальном мире технический писатель реально не должен ничего, кроме как сидеть в уголочке и тихонько писать свои инструкции. Но живем мы в мире реальном. И я считаю, что техпис еще много чего должен (при условии получения соответствующего поощрения от работодателя). А за тех, кто «не должен» рынок все сам порешает.
Что скажете?
💯16❤3🌚1
Техписа на них нет...
Увидел в лифте такие вот правила пользования.
И они мне сломали мозг. Попросил жену и детей посмотреть на это и сказать, что здесь не так.
И все трое, включая 10-летнего ребенка, указали на одну и ту же проблему (которую я тоже сразу увидел).
Как думаете, что смутило всех в этой картинке?
Увидел в лифте такие вот правила пользования.
И они мне сломали мозг. Попросил жену и детей посмотреть на это и сказать, что здесь не так.
И все трое, включая 10-летнего ребенка, указали на одну и ту же проблему (которую я тоже сразу увидел).
Как думаете, что смутило всех в этой картинке?
🤯3😱1