PRO_техписательство
558 subscribers
92 photos
1 file
45 links
Канал техписа с дипломами программиста и аналитика. Пишу про техписательство и всё, что около него.
Адепт Docs as code.
До этого 9 лет работал IT-копирайтером и редактором на фрилансе. Так что про фриланс знаю всё. А еще пишу стихи, в т.ч. на заказ.
加入频道
В своем докладе я упомянул, что с помощью Foliant и Slate также можно документировать и gRPС API (на слайдах этого нет).
Исправляю ситуацию (для тех, кто спрашивал про это после доклада).
Вот ссылка на тулзу proto2slate, которая конвертирует файлы .proto в Markdown.
Полученный Markdown скармливаем Слэйту и получаем справочник API.
На скринах — фрагмент содержимого файла .proto и скрин сайта, который из этого получается.
🔥5🤝21
Потренироваться в работе с консолью, небоясь ничего сломать

Техпис, держи сервис «Теминатор», который БЕСПЛАТНО дает возможность потренироваться в работе с консолью (терминалом). Здесь ты прямо в браузере можешь работать с терминалом.

Плюсы: можно делать все, что угодно (но главное на перестараться, а то вдруг еще IP заблокируют).

Минус: время одной сессии ограничено 15 минутами.
🔥84👍2
Про фэйлы при работе с текстами

Наверняка у каждого, кто работает с текстами, случались фэйлы, которые «уезжали на прод».
У меня такое было.

Самый яркий фэйл случился в 2012 году, когда я слепил для себя сайт, чтобы привлекать клиентов на копирайтинг. Сделал сайт, а в подвале разместил «Агенство копирайтинга» (без буквы т). Благо, не на всех страницах так было (сайт делал вручную в Macromedia Dreamwiever, шаблоны не использовал: только кропотливый ручной труд 😀).

И висело все это добро в интернете несколько месяцев. Заметил я фэйл просто случайно: стыдно было, очень стыдно.
К слову, клиенты все равно приходили. Даже банк один удалось привлечь: писал им тексты для проекта по платежным терминалам.

Так что, вычитывайте свои тексты, чтобы не было обидных фэйлов. А я до сих пор не очень-то люблю вычитывать свои же тексты.
5👍3👎1🔥1
Прежде чем в доку код добавлять
Нужно его сквозь форматтер прогнать


Сегодня кучу времени потратил на правку примеров кода (примеры использования DSL) в доке для in-memory базы данных, за которую я отвечаю. А все почему? Да потому, что в начале работы над документацией я добавлял туда примеры, копируя их прямо из Postman (позже все-таки стал прогонять через форматтер). А он, собака, добавляет лишних пробелов, из-за чего код может выглядеть не очень красиво.
В итоге — более 60 правок в 22 файлах. А ведь это время можно было потратить с куда большей пользой 🙃

Чтобы не быть как я, пользуйтесь форматтерами, которые красиво форматируют код, и он гарантированно смотрится в доке красиво.

Чем пользоваться? Категорически рекомендую онлайн сервис jsonformatter.org. И ничего, что в названии у него «json». Сервис отлично форматирует куски кода на разных языках (см. скрин).

Кроме форматтера здесь есть и другие полезные функции. Например, этот сервис может превратить JSON-объект в код на Go или Java, в котором формируется соответствующая этому объекту структура. Я эту функцию использовал при тестировании Go-коннектора для подключения к той самой in-memory базе данных.
👍7👎1🔥1🤝1
Что читает техпис?

Забрал с пункта выдачи замечательную книгу. Начал читать ее в электронном виде, но решил заказать "живую". Не люблю читать через экран.
👍9🔥51
Отличная новость.
А у меня уже есь тема и тезисы для доклада (еще на 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 июля включительно.
Сегодня же день фрилансера!!!

Не могу остаться в стороне от этого праздника, т.к. сам 9 лет фрилансил.
С праздником всех причастных. Желаю интересных проектов и адекватных заказчиков.
8👏5
Из копирайтерского: Работать по 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 умения в фактчекинг.

Но, в общем и целом, это реально. Есть над чем задуматься. Некоторым кожаным мешкам стоит напрячься :).
Что скажете?
Please open Telegram to view this post
VIEW IN TELEGRAM
❤‍🔥3🔥3👾3
Красивый номер мердж-реквеста у меня сегодня получился.
🔥5❤‍🔥3
Как изобразить мэппинг (маппинг, mapping) данных в разных системах (источниках)

В этом посте под мэппингом понимается это соотношение между данными, которые находятся в разных системах.

Как техпису описать мэппинг данных? Хороший и понятный большинству способ — отобразить процесс визуально.
На скрине — простой пример, как это может выглядеть.
Согласитесь, здесь все предельно понятно: что откуда берется в одной системе и куда сохраняется в другой, как при этом преобразуются данные (если есть преобразование).

А какими инструментами можно это делать?
Вариантов масса. Хочешь — рисуй руками. А хочешь — кодом. Мне ближе второй вариант. Про него расскажу в одном из следующих постов.
👍6🔥4
НЛО прилетело, приглашение принесло

Решил я на днях побороть вселенскую несправедливость и стать автором на Хабре.
Не порядок ведь: писал на Хабр не раз, но было это всё для клиентов, а публикаций от своего имени не было (хотя зарегался там в 2016 году).

И вот свершилось. Пару дней дней назад добавил на Хабр статью по материалам моего доклада на TW Days#1, а сегодня после обеда ее выпустили из песочницы.
Вот, собственно, статья.

Теперь я официально «Захабренный» (только бы не заминусовали новичка).
🔥153😁1
Регулярки можно изображать в виде схем

И делается все без особых напрягов.

Вы знали об этом? Я — нет. И только недавно узнал.
А ведь очень удобно.

И готовый инструмент для такой задачи есть. Это — 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-глаголу):

- 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 — это «родня» фразы «Без нормального ТЗ результат будет ХЗ».

Что скажете?
🤝135
Умели же когда-то обложки привлекательные для книг делать

Разбирал вчера свои книжные запасы и нашел эту книгу из 2013 года.
Кстати, книга просто офигенская. После нее я вкатился в написание экспертных статей для SEO-специалистов и интернет-маркетологов. Сейчас, конечно, SEO другое, но основы основ из этой книги можно почерпнуть.
🔥6😁5
Ура!!! Я только что защитил дипломный проект!!!

8 месяцев обучения пролетели незаметно. И было это продуктивно.
Теперь я не только технический писатель, но и подробности позже.
🔥12🏆9👍2👏1
Техпис не должен... Или рынок все порешает

Наверное, это холиварная тем, но все-таки.

Что-то в последнее время все чаще стали попадаться высказывания типа «Техпис не должен...». Как правило, они всплывают в обсуждениях вакансий.

У большего количества таких высказываний посыл такой: мол техпис не должен делать ничего, кроме как писать инструкции.

Они говорят, что техпис не должен:
- описывать архитектуру,
- участвовать в написании спецификаций,
- лезть в код и разбираться с тем, чего там понаписали разработчики,
- настраивать пайплайны сборки документации,
- рисовать диаграммы за аналитиков и архитекторов....

А вот я так не считаю. Я думаю, что техпис должен. Должен стремиться к тому, чтобы пощупать всё, попробовать всё, понабивать шишки обо всё.
Должен, но с оговоркой: если работодатель достойно за это платит (достойная оплата — это тема для отдельного разговора).

Почему техпис должен? Я считаю, что это полезно для него же в первую очередь. Я уверен, что востребованный на рынке технический писатель — это T-shape специалист. А как стать таким специалистом, если ты свято веришь в «Техпис не должен»?

Водитель фуры, например тоже не должен менять колесо (для этого есть специальные бригады). Но большинство дальнобойщиков не ждет, пока к ним приедет эта самая бригада. Они берут и делают все самостоятельно.
Разработчики, по-хорошему, не должны настраивать CI/CD для своих продуктов (есть же девопсы под это дело). Но знаю, что многие сами это делают.


Да, может быть, в идеальном мире технический писатель реально не должен ничего, кроме как сидеть в уголочке и тихонько писать свои инструкции. Но живем мы в мире реальном. И я считаю, что техпис еще много чего должен (при условии получения соответствующего поощрения от работодателя). А за тех, кто «не должен» рынок все сам порешает.

Что скажете?
💯163🌚1
🚢 Я в отпуске, поэтому пост с морем и корабликами. Ещё надумал серию постов про docs as code (про диаграммы, как код, если точнее). Не переключайтесь.
11😎2
Техписа на них нет...

Увидел в лифте такие вот правила пользования.
И они мне сломали мозг. Попросил жену и детей посмотреть на это и сказать, что здесь не так.
И все трое, включая 10-летнего ребенка, указали на одну и ту же проблему (которую я тоже сразу увидел).
Как думаете, что смутило всех в этой картинке?
🤯3😱1