Жду новый пост

Серия «Грол-о-работа»

Всем привет! Я работаю техническим писателем почти три года. Хочу поделиться историей о том, как я смог войти в IT без опыта программирования и профильного образования.

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

О чём пойдёт речь

В статье я расскажу важных темах на своём собственном примере:

• Почему не пошёл в IT сразу

• Гуманитарное образование и первый опыт работы

• Как я впервые попал в IT и как через месяц меня уволили

• Как загорелся идеей стать техническим писателем, что за профессия

• Собственные ощущение от новой работы

Почему стал гуманитарием

В школе я всегда был более дружен с компьютером, чем с одноклассниками. Когда у нас только появился интернет, я скачал шаблоны HTML и CSS и склепал на них свой первый сайт. Заменил картинки и текст на свои и залил в продакшен.

Такие маленькие детали могут формировать будущее. Если вы в детстве пробовали работать с HTML/CSS, это может стать хорошей отправной точкой для будущей карьеры фронтэдера.

Если бы уделял больше внимания своим увлечениям, я мог бы поступить, например, в ИТМО, сейчас бы работал «на фронте». Но в 2007 году я даже не знал про существование IT-сферы, тем более не был в курсе, что такая работа может быть потенциально доходной и этому где-то учат.

Зато мне всегда нравился английский и очень сильно хотел быть переводчиком. Поэтому поступил в РГПУ, Выборгский филиал и вышел оттуда с дипломомфилолога-учителя английского языка.

Первая работа по специальности

Моей первой работой был «Лингваториум» — это онлайн-тренажёр, который позволяет научиться английскому при помощи разнообразных языковых упражнений. Так вот, вопреки расхожему мнению не все гуманитарии работают на кассе в Мак… Вкусно — и точка.

Любой первый опыт работы — ценное приобретение, это целая строчка в резюме. Даже если работа непрофильная, её всё равно можно повернуть профильным краем. Например, так:

• Для преподавательского резюме я описывал свой опыт как «анализировал учебные пособия, чтобы создавать обучающие упражнения».

• Для переводческого резюме я писал «составлял упражнения на основе англоязычных учебников, переводил упражнения на русский».

• Для резюме технического писателя: «изучал учебные материалы для технических специальностей, при необходимости менял формулировки».

Этим всем я хочу сказать, что любая специальность — не приговор, а скорее наоборот. Особенно в начале карьеры.

После бакалавриата я продолжил обучение в магистратуре, в это время подрабатывал фриланс-переводами. Заказов было не много, платили ещё меньше, зарабатывать получалось плохо. Полноценную работу без ущерба для учёбы я смог позволить себе только через два года. Это была хорошая и высокооплачиваемая должность переводчика на стройке Лахта-центра.

В будущем я очень много щеголял этим опытом. Шикарная строчка для резюме технического писателя, ведь я мне приходилось разбираться в документации, знакомиться с оформлением по ГОСТу. Такая строчка в резюме даст потенциальному работодателю сигнал о том, что вы ознакомлены с требованиями ГОСТов, с языком и основной структурой технической документации, даже если документация была не для программных продуктов.

Я ушёл со стройки из-за неприятной рабочей атмосферы и желания продолжить учёбу в аспирантуре. Возомнив себя ютюбером, я запустил свой ютюб-канал про переводческую деятельность с настолько плохим качеством монтажа и графики, что это даже было смешно.

Аспирантуру я так и не закончил, вместо этого поработал годик менеджером по ВЭД, но по сути мои обязанности сводились к переводу видеоконференций и писем от иностранных партнёров.

Брошенная аспирантура может плохо сыграть в резюме. Если спросят, лучше сказать честно: «мне не понравилось, что акцент не на исследовательской деятельности, а на преподавании».

Работа мечты (уволили через месяц)

От этой работы у меня остался сувенир — дед мороз, подаренный генеральным директором. После ухода мне казалось, что я ни к чему не пригоден. Был переводчиком — ушёл. Был менеджером по ВЭД — ушёл. Пора двигаться куда-то дальше.

Мне нравилось переводить, нравилось разбираться в деталях и писать тексты. «Ты не думал стать техническим писателем, тебе бы подошло», сказал мне как-то знакомый. И я загорелся идеей, начал читать, изучать вакансии, требования, даже начал откликаться на вакансии, но никто не отвечал на отклики.

Не стоит бросать попытки, если отклики не приносят результата. Спрашивайте обратную связь каждый раз. Любой ответ помогает понять, на что следует обратить внимание в следующий раз. Если обратной связи совсем нет, можно попробовать переписать резюме, почитать подробнее о желаемой профессии, получить новые навыки, о которых пишут в описании вакансий.

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

Сразу при оформлении начались проблемы:

• Серая на 2/3 зарплата, к тому моменту от серой з/п я уже устал.

• Оформление растянулось на неделю, тянули с подписанием документов.

• Задачи и обязанности не были понятны. Не было вводного инструктажа, не было понятно, для чего я делаю свою работу и каков её результат, соответственно, удовлетворения от работы тоже не было

Целый месяц я креативил и генерил идеи изо всех сил, а потом меня уволили без объяснения причин. Об увольнении я узнал по «третьей зарплате за месяц» с подписью «расчёт при увольнении». Первая попытка стать айтишником провалилась.

Ещё одна строчка, которая не украсит резюме. Исправить ей можно тремя способами:

1. Во-первых, можно её не указывать, потому что это слишком маленький период.

2. Во-вторых, всегда можно объяснить причину.

3. В-третьих, обязательно использовать этот опыт в свою пользу. Я работал с YouTrack, Markdown, работал с IT-продуктом и писал околоайтишные тексты как, например, политика использования персональных данных. Хороший и полезный опыт.

После увольнения я решил заняться своим портфолио и по-настоящему углубиться в изучение профессии технического писателя. Я откликнулся на вакансию Selectel, где писал заказные технические статьи. Это тройной профит: я писал про сетевую модель, про гит, LVM, тем самым повышая свою подкованность в сфере информационных технологий, нарабатывал портфолио и получал доход.

Источник: vladimir-markiev.name

Работа на Selectel вдохновила создать свой сайт. Только в этот раз я написал его с нуля на чистом HTML и CSS. Получилось гораздо лучше, чем первый сайт в старшей школе. Свой собственный сайт повышает шансы быть замеченным и наглядно демонстрирует навыки. Благодаря всем вложенным в поиск новой работы усилиям, я получил сразу несколько оферов, даже пришлось выбирать между ними.

Чем занимается технический писатель?

Столько рассказал про путь, но так и не пояснил, чем занимаюсь. Технический писатель — это профессия на стыке. Он создаёт документацию для IT-продуктов. Может создавать документацию, например, в «ворде» или в специальных программах с использованием языков разметки. К сожалению, образование технического писателя нельзя получить в каком-то официальном ВУЗе. Можно либо пройти обучение на платных курсах, либо самостоятельно прийти в профессию.

Чтобы заниматься документацией, нужен особый склад ума и характера, нужно уметь общаться с разработчиками, аналитиками и тестировщиками на них языке и создавать из этого документацию. Нужно уметь ставить себя на место простого пользователя, администратора или даже разработчика. Желательно уметь читать код, нередко техписы также тестируют соответствие документации реальности.

Компания, в которой я работаю уже прошла путь от документации в «ворде» и на момент моего прихода всё уже было «по-взрослому»:

• Docs as code в формате DITA

• Исходники загружаются в git

• DITA-файлы конвертируются в PDF

Если вы только начинаете свой путь, то на собеседовании будет очень уместно спросить про docs as code, текущий формат документации, а также git. Если вы не разбираетесь в вопросах, то их изучение будет хорошей отправной точкой.

Вскоре мне поставили задачу разобраться в возможности переноса документации в онлайн. Сделать разделение на версии, прикрутить сквозной поиск и выложить по адресу в интернете. Мне очень понравился процесс, я уже писал о нём в других своих статьях, которые можно прочитать, например, на хабре.

Как ощущаю себя в новой профессии

В первую очередь хочется отметить, что все айтишники — очень открытые люди. Неадекватные тоже есть, как я убедился из опыта работы копирайтером, но их меньшинство. В моей текущей компании работают по-настоящему крутые и увлечённые своим делом люди. Это даже не коллектив, а настоящая семья: все относятся друг к другу с дружелюбием и уважением. Любой сотрудник может обратиться к любому и получить адекватный ответ, без агрессии или предвзятого отношения.

Сперва коллеги-разработчики казались мне олимпийскими чемпионами. За спринт они успевают написать код, объединить фронтэнд и бэкэнд, а потом представить наработки всему отделу или всей компании. Сейчас я тоже подтянулся, стал выполнять больше задач за меньшее время и понимаю, что просрочки случаются у всех и никому не просто.

В документации тоже встречаются ошибки. Сперва было сложно, но теперь я научился воспринимать такие ошибки как потенциал для улучшения, ведь это не что-то личное.

Вместо итога

Путь к новой профессии — это не гонка на скорость. Перейти из гуманитарного образования в сферу информационных технологий сложно и долго, это требует работы над собой и складом мышления. Искать своё место придётся методом проб и ошибок, но поиск того стоит, если это именно то, чего вы хотели достичь.

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

А с каким образованием вы пришли в IT?

P.S. Есть такой стереотип, что все айтишники носят бороды. Но я не видел таких стереотипичных айтишников с бородой у нас в компании или в других. Да и у самого борода никогда не росла.

Можете глянуть другие материалы по теме перевода в подборке и подписаться на мой канал в телеграме @grolchannel, где я публикую разнообразные посты значительно чаще.

Всем лучи добра! Меня зовут Сергей Карасёв, но вы можете звать меня просто Саня. Я работаю техническим писателем в одной компании. Расскажу вам о двух Docs as Code инструментах. На случай, если вы делали документацию в ворде или ещё где-то, а теперь решили отделить форматирование от документации и захотели "чтобы было чисто!". Побуду сегодня вашим Мистером Пропером.

Когда я только пришёл в компанию, наша документация была на DITA. Но потом мы решили модернизировать документацию, вывести в онлайн, чтобы была разбивка на версии, чтобы всё было красиво и т.д. и т.п. Подробнее можно прочитать вот здесь и вот тут.

То есть я работал с Дитой, и я работал с AsciiDoc, поэтому в какой-то степени могу судить и сравнивать. Сравню аналогичные функции, расскажу об отличиях, плюсах и минусах каждого формата и т.д. Короче, всё чётко и по понятиям, как это делают у нас в Купчино.

Документация

DITA

Нельзя стать священником, не прочитав Библии.

В случае Диты Библия - это стандарт, задокументированный чуть больше, чем полностью. Но нужно быть психом, чтобы втыкать в целый стандарт.

К счастью, есть Евангелие от Radu Coravu - документация от создателей Oxygen. Oxygen - это основной инструмент для работы с Дитой, но об этом позже.

Хочется чего-то более человечного? Есть свободное толкование Библии с примерами - Learning Dita. Очень помогло, когда я хотел лучше понять Диту.

AsciiDoc

Есть только одна Библия - сайт docs.asciidoctor. На сайте задокументирован весь синтаксис с очень удобной рубрикацией. Не знаете, как это сделать -- используйте поиск по сайту.

Есть ещё несколько мест, где можно найти документацию, но они либо неофициальные, либо устаревшие.

Я далеко не сразу нашёл Docs.AsciiDoctor. Кто победил? Пусть будет ничья.

DITA:AsciiDoc 1:1

Работа с исходниками

DITA

Исходники - обычный текст, который можно редактировать в блокноте. Проблема в том, что это XML с очень строгой структурой.

Иными словами: нужно иметь стальные... нервы, чтобы писать на дите в блокноте.

AsciiDoc

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

Иными словами: писать в блокноте можно без проблем.

DITA:AsciiDoc 1:2

Редакторы для работы с исходниками

DITA
Для Диты есть одна основная утилита - Oxygen. Это коммерческая и платная утилита. Есть ещё несколько утилит, но, честно говоря, они не очень удобные. Oxygen - это всё же канон. И стоимость у него каноничная.

А ещё новая версия несовместима со старой лицензией. Ну, разумеется.

AsciiDoc

Официального или единого редактора не существует. Но есть несколько редакторов, которые поддерживают AsciiDoc при условии установки плагинов:

- Atom - не пробовал, но выглядит норм, много плагинов.

- Visual Studio Code - с плагином AsciiDoc поддерживает синтаксис и большую часть функций.

- IntelliJ Idea - плагин поддерживает максимум функций и постоянно обновляется.

- AsciidocFX - утилита для работы с синтаксисом AsciiDoc. Поддерживает синтаксис.

Все утилиты для работы с Asciidoc абсолютно бесплатны.

DITA:AsciiDoc 1:3

Набор функций

Повторное использование

DITA

Все любят Диту за повторное использование кода.

Можно использовать целые топики или любые фрагменты. Но есть ограничения, в зависимости от разрешённых элементов. Oxygen не даст заимствовать запрещённые элементы, так что ошибиться сложно.

Заимствования делаются при помощи "conref" или "conref ... conrefend". Заимствовать один элемент или топик полностью - "conref". Заимствовать от и до - "conref ... conrefend".

AsciiDoc

Механизм повторного использования аналогичен Дите. Заимствовать один элемент или топик целиком - "include::topic.adoc[]". Заимствовать от и до чуть сложнее. Нужно создать два тэга:

//tag::magic-tag[]

Бла-бла-бла

//end::magic-tag[]

Затем заимствовать по тэгу: "include::topic.adoc[tags=magic-tag]".

DITA:AsciiDoc 2:4

Ключи

DITA

Сначала ключ нужно обозначить, затем задать ему значение, потом использовать его в нужных местах. Сделать это вне Oxygen будет очень сложно. Мне сложно сделать это даже в Oxygen, придётся рыться в заметках. Если честно, проще не использовать ключи.

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

AsciiDoc

Здесь ключи называются атрибутами, но суть та же. Определяешь в топике, потом используешь. Задаются атрибуты очень просто: ":attribute: значение". Использовать через "{attribute}", что заменится на "значение".

Область действия задать тоже можно, но не так просто в чистом AsciiDoc. Удобнее использовать Antora - генератор статических сайтов для AsciiDoc. Если не нужен сайт, то область действия ключей будет только в рамках топика или "карты".

DITA:AsciiDoc 3:5

Профили и фильтрация

DITA

Даже если вы знакомы с Дитой на уровне "знакомый по пьяни рассказывал", вы должны были слышать о невероятно крутом механизме профилирования.

На пальцах: это когда создаётся один документ на 15 страниц исходников.

Да, такой небольшой документ.

Из этих 15 страниц одной командой мы делаем три документа по 5 страниц каждый. При этом инструмент понимает сам, какие 5 страниц куда идут, и добавляет к каждому титульный лист и все остальные части.

Вот для этого в Дите есть специальные пометки - профили, ".ditaval файлы". В Дите это делается очень легко и удобно.

AsciiDoc

В AsciiDoc тоже есть схожий механизм, но тут больше ручной работы. Сначала нужно задать атрибуты на каждой странице, которую мы хотим включить в руководство и т.д. и т.п.

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

Это посложнее, чем у Диты.

Есть три вида условий:

- ifdef - если атрибут определён, контент включается.

- ifndef - если атрибут определён, контент не включается

- ifeval - если атрибут равен условию, контент включается. Условия типа равен, не равен, больше, меньше и т.д.

Кстати, даже Антора не сильно упрощает профилирование. В чём-то даже усложняет. Зато так можно настроить область использования атрибута.

На пальцах: определил атрибут в главном топике, включил в него все остальные. В остальных определил ifdef, ifndef, ifeval. В зависимости от указанного в главном топике атрибута получишь разный результат. Можно создать несколько почти одинаковых главных топиков с разными атрибутами и быстро штамповать документы по 5 страниц.

DITA:AsciiDoc 4:5

Форматы экспорта и единый источник

Единый источник - это то, ради чего мы здесь сегодня собрались! То, ради чего в принципе переходят на docs as code.

Ага, здорово, а что это? Не все могут быть в курсе, поэтому быстро поясню. Единый источник - это когда из одного исходного кода можно получить несколько форматов документации. Например, получить сразу .pdf, .html, .doc(x), и не придётся конвертировать и поправлять -- результат всегда будет стабильно одинаковый.

DITA

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

Чтобы трансформации (по-народному - экспорт) работали, необходимо установить JDK и DITA OT (DITA Open Toolkit).

В принципе, можно обойтись и одним Oxygen, в него уже включено всё необходимое, но он платный.

В общем, вы поставили JDK, DITA OT и можете смело пользоваться всеми перками единого источника из коробки.

Из коробки доступны вот такие форматы:

Можно также установить дополнительные плагины, чтобы иметь ещё больше форматов (смотри документацию DITA OT).

Но вы наверняка захотите, чтобы конечный документ соответствовал корпоративному стилю (проклятые капиталисты, при коммунизме-то всё одинаковое и никто не выпендривается!). Всё ещё хотите? Добро пожаловать в мир XSL-трансформаций!

- Не-не, я не подписывался на какие-то XSL-трансформации, я ничего о них не знаю!
- Это Дита, детка! Хочешь кататься на Дите, люби и XSL-трансформации.

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

Короче, настроить свой плагин для трансформации сложно. Но возможно при определённых знаниях.

AsciiDoc

Здесь ситуация та же. Ну только что развернуть проще. Всё можно сделать из командной строки.

Есть вот такие встроенные конвертеры:

И вот такие официальные аддоны:

Помимо этого, есть много разных "любительских" конвертеров. Это всё то, что за годы сделали пользователи AsciiDoc. Много разных форматов. Наверное, самый распространённый - это pandoc, который конвертирует ещё много чего много во что. Соответственно, настраивать внешний вид и стили можно по-разному. Введите в ваш любимый поисковик "asciidoc to нужный формат" и изучите результаты.

А ещё из Asciidoc можно создавать целые статичные сайты при помощи генератора статичных сайтов Antora.

- Вот ты говоришь "статичные сайты", а что это такое?
- Это обычный HTML-сайт, только без всяких лишних наворотов типа CMS, движка и прочего. Короче, не запаривайтесь, просто обычный сайт.

Можно создавать сайты с дефолтным или кастомным внешним видом. Причём в случае с сайтом настройка внешнего вида гораздо проще. Чтобы поменять ширину, цвета, шрифт, достаточно знать немного HTML и CSS.

Иными словами, это совсем не сложно, точно легче чем XSLT.

А ещё почти из любого редактора можно создать pdf, а то и нескольких видов.

Никому не дам балл. Создать трансформацию/конвертер со своим стилем не так просто ни в AsciiDoc, ни в Дите.

А чего я хотел? А хотел я, чтобы в идеале как с Antora. Чтобы максимально интуитивно и без всяких извращённых навыков. Ну, в идеале.

DITA:AsciiDoc 4:5

Обратная совместимость

Последний важный пункт, на мой взгляд. Кто-то скажет "а зачем мне обратная совместимость, и что ты вообще подразумеваешь под этим?"

Ну, например, выходит новая функция. Новый конвертер или новая возможность в синтаксисе. Наверняка вы захотите этим воспользоваться. Я захочу. Не убедил? А если новые исправления безопасности? По-моему, это важный повод обновиться.

DITA

Обычно все изменения Диты оперативно поддерживаются в новых версиях DITA OT. Только вот новая версия DITA OT вполне может сломать вашу созданную трансформацию. Ну вы просто не сможете обновиться и получить преимущества новой фичи, пока не обновите свой плагин. А это опять XSL-трансформации с кровью, потом и баттхёртом.

AsciiDoc

Обратная совместимость AsciiDoc обычно не проблема. Новая версия всегда будет поддерживать прежние фичи, обновление не вызовет проблем. А если проблемы всё-таки могут возникнуть, то об этом обязательно будет сказано в списке изменений.

Серьёзно, я даже не знал, что так бывает. Что можно просто обновиться и всё будет работать, как раньше. Очень приятно.

DITA:AsciiDoc 4:6

Техническая поддержка

DITA

Чуть не забыл. Сама по себе Дита лишена какой-либо техподдержки. Максимум, на что можно рассчитывать - это помощь на StackExchange. Ну, ещё можно попробовать задать вопрос на форуме Oxygen. Скорей всего ответят.

AsciiDoc

Поддержка феноменальна. Можно спросить в чате AsciiDoc, на гитхабе или в твиттере.

Всегда ответит кто-то из сообщества или даже сам создатель.

DITA:AsciiDoc 4:7

Итог

При сравнительно похожем наборе функций AsciiDoc проще, чем DITA, а во многом даже превосходит её.

Дита выигрывает в повторном использовании, фильтрации и возможностях тонкой настройки ключей. У AsciiDoc отличная поддержка, обратная совместимость и редакторы для работы с исходным кодом.

Основная цель этого материала - сказать, что выбирать инструмент нужно с умом. Не стоит сразу выбирать Диту как инструмент по умолчанию. Подход docs as code открывает большие возможности. Но сначала нужно подумать, а нужны ли вам эти возможности.

Всем лучи добра и качественной документации!

Заглядывайте в мой телеграм, если что. Пишу разные интересные и не очень вещи.