PRO_техписательство
556 subscribers
92 photos
1 file
45 links
Канал техписа с дипломами программиста и аналитика. Пишу про техписательство и всё, что около него.
Адепт Docs as code.
До этого 9 лет работал IT-копирайтером и редактором на фрилансе. Так что про фриланс знаю всё. А еще пишу стихи, в т.ч. на заказ.
加入频道
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
Долго не можете найти техписа? Возможно, вам нужно поменять рекрутера

За последний месяц я получил 16 предложений от разных компаний (работу, если что, пока не ищу, они просто сами на меня выходят).
Заметил одну вещь. Ну как заметил, я и ранее, когда занимался контентом для агентства IT-рекрутинга, об этом знал. Но думал, что сейчас все стало лучше.
А вот хрен. Ничего лучше не стало, и многие HRы и рекрутеры не хотят работать.

Почти каждому из написавших мне я задавал уточняющие вопросы по вакансии. Из 16 вакансий вопросов не возникло по 6 (там все было понятно и доходчиво расписано).
По десяти полученным предложениям были отправлены уточняющие вопросы (про вилку, стек, условия удалёнки и пр.). И только по трем была получена обратная связь. Остальные 7 HRов (или рекрутеров) просто молча отвалились. Естественно, когда они придут в следующий раз с предложениями, так же столкнутся с молчанием :) Я неверю, что они могут искать ответы на вопросы по 1-2 неделе, если что.

Вот вам и причина долгих поисков. Она на поверхности: кто-то на букву «Эйчар» или «Рекр» просто не хочет нормально работать.

Недавно в одном из каналов для бизнесменов рассматривался похожий кейс. Компания более полугода не могла найти сварщика. Когда начали разбираться, куда ж делись все сварщики, проанализировали критерии, по которым HR вела поиски (и чуть не поседели). Среди критериев там был возраст до 30 лет, амбициозность и … барабанная дробь … активность в Инсте (активность в Инсте сварщика, блеать!!!). За поиски взялся руководитель и нашел спеца за 3 дня.

Техписы, конечно, не сварщики, но подход к их поиску, как я погляжу, у некоторых примерно такой же — спустя рукава.

Удачи в поисках. И если они затянулись, бегите к HRу (рекрутеру) и смотрите, что и как он это делает.
💯11👍1
Идентификатор ресурса в API. Когда его можно назвать хорошим

Идентификаторы (далее ID) позволяют однозначно идентифицировать (простите за тавтологию) конкретный объект (или ресурс API в нашем случае). И к их формированию не стоит подходить «спустя рукава»: хотя казалось бы, что там придумывать, просто взял и пронумеровал все (нот нет, не прокатит).
В разных источниках встречается от 5 до 8 атрибутов (или признаков), за счет которых ID можно назвать хорошим. Больше всего мне понравилось, как это сформулировал Д. Гивакс.
Он выделяет следующие атрибуты хороших идентификаторов ресурсов API:
1️⃣ Уникальность.
2️⃣ Непредсказуемость.
3️⃣ Простота использования.
4️⃣ Постоянство.
5️⃣ Быстрота и легкость генерации.
6️⃣ Читабельность.
7️⃣ Информационная плотность.

Подробно эти атрибуты (если не все, то большую часть) разберем в следующих постах. И тогда вы поймете, почему использовать в качестве ID просто цифры по порядку с единицы (или нуля) и далее — не есть хорошо, или почему в идентификаторах не рекомендуют использовать некоторые буквы, цифры и символы.
4👍1
package main

import "fmt"

func main() {
fmt.Println("С 256 днем вас, господа программисты и все причастные!!!")
}
🎉81
Вопрос для утра пятницы.
Метод GET в HTTP API:
Anonymous Poll
57%
Всегда идемпотентен. Зуб даю.
43%
Ну нет же, не всегда.
2🔥1💩1🤡1
Кто хочет вкатиться в Docs as code? У моего коллеги в канале стартовал курс (бесплатный!!!!) для новичков.
Присоединяйтесь, Антон плохому не научит.
🔥7
Forwarded from Parawriter
Привет!

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

Что скажете, если мы проведём практический курс по docs-as-code? Будет весело — познакомимся с подходом «Документация как код» (в моей интерпретации), настроим инструменты и организуем настоящий процесс работы с документацией через git с последующей публикацией на сгенерированном html-сайте. Всё по-настоящему, но без трудностей и нюансов, которые встречаются на пути техписателя в реальной рабочей жизни.

Назовём этот курс как-нибудь романтично — маэстро! Docs as code для самых маленьких.

Работаем по проверенной схеме — посты курса будут публиковаться с хештегом #docsascode в хронологическом порядке и с относительно стабильной периодичностью 🙃

Право перебивать тематические публикации чем-то ещё оставляю за собой:)

Надеюсь, мы все хорошо проведём время!

P.S. Курс бесплатный, но ваши сердечки, птички, рукопожатия и даже звёздочки будут лучшей наградой!

#практика
🔥17
А не хотите мини-курс по документированию API?

Хочу сделать мини-курс по документированию HTTP API.
Но не совсем прям только по документированию.
Я вижу это все так:

1. Мы спроектируем свой API. Небольшой такой, буквально на несколько методов. Это позволит вам немного побыть в роли того, кто этим занимается, и в общих чертах понять, как это все происходит.
2. Далее мы создадим для этого API спецификацию в формате Open API. И это уже будет одним из видов документации.
3. Затем из полученной спецификации мы сгенерируем статический сайт-справочник. Для этого будем использовать Foliant. Возможно, попробуем и другие инструменты, чтобы почувствовать разницу.
4. Напишем доку вручную (как будто у нас нет Open API-спецификации) и снова генерируем сайт-справочник из всего этого.

И не хотелось бы, чтобы на этом все закончилось. Я думаю (не обещаю, но хотелось бы это реализовать), что мы замокаем API, либо развернем его с помощью специального сервиса, или же вообще сгенерируем код бэкенда и разместим все это дело где-нибудь. Потом «подергаем API-ручки», чтобы вы знали, с какой стороны подойти к API.

Как вам идея? Если этот пост наберет 30 сердечек ❤️ к исходу среды (18 сентября), мини-курсу быть, не наберет — ну и фиг с ним, с этим курсом.

Все будет происходить здесь, в этом канале.

Предложения и пожелания приветствуются: оставляйте их в комментах. И если знаете кого-то, кому это может быть интересно, приглашайте в канал.
147🔥8