#какэтоработает #писалитирекомендует
Всем привет!

По следам мема прошлой недели давайте поговорим о критике текста :)

Когда вы начинаете писать тексты, то, скорее всего, к ним первое время (да и не только первое) могут прилетать правки. Не стоит относиться к комментариям так, словно ваша карьера на этом закончилась и вас сейчас выгонят с работы. Нет! Ревьюер обычно оценивает именно текст, а не вас, если это не какой-то частный случай с вашим заклятым врагом.

Когда могут быть полезны правки?

1. Когда вы долго сидите над текстом, то глаз так или иначе “замыливается”.
Из-за этого вы можете не заметить сложных оборотов, опечаток или чего-то ещё. Поэтому если вам оставили комментарий, что “сложное предложение”, “опечатка” или “не хватает запятой”, и вы понимаете, что ревьюер прав, значит, всё в порядке. Поблагодарите коллегу и исправьте ошибку.
2. Когда вы попадаете под “проклятие знания”.
Например, если вы долго сидели над новой фичёй, то при её описании вы можете не заметить, как пропустили какой-то шаг. А всё из-за того, что в вашем восприятии он отложился как “само собой разумеющееся”.
3. Когда вы только начинаете свой писательский путь.
Это самое лучшее время для впитывания замечаний от более опытных коллег. Поэтому если пришло 20 комментариев на одну статью — это не всегда плохо :) Плохо, если они не конструктивны, а в остальных случаях — очень полезны.

Если вы понимаете, откуда растут ноги критики или ревьюер подробно объяснил свою точку зрения, правки всегда будут иметь положительный эффект. И ваша задача — провести работу над ошибками: понять, за что зацепился ревьюер, исправить это и в дальнейшей работе придерживаться новой установки. Возможно, сначала придётся себя “насильно” поправлять, но в какой-то момент вы привыкните.Так вы совершенствуетесь.

Пример для воодушевления, почему получать обратную связь — это всегда хорошо:

🎤 Аманда Палмер — спикерша TED, чьё выступление в своё время вызвало шквал положительных реакций. В своей заметке о подготовке к выступлению она выразила благодарность 105 людям, которые давали обратную связь по её речи (изначально — тексту). Потому что каждая точка зрения может привнести в речь (или в нашем случае текст) что-то, чего в ней не хватает, но что будет полезно.

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

В общем, не бойтесь критики, если она конструктивная — она поможет вам стать лучше как профессионалу. И какой бы она ни была — не воспринимайте её на свой счёт.

А как вы относитесь к комментариям к вашему тексту?

#практика #пользовательскоеписалити
Всем привет! С вами Техписалити! Практика.
Спасибо всем, кто присылал домашку. Не забывайте, что у нас не диктатура кураторов, и можно возражать, если особо хочется.
Целевая группа: начинающие без опыта работы.
Уровень сложности: минимальный.

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

С чего начать? Конечно, любая дока начинается со скелета. Но как его построить?
В нашей практике встречались два разных подхода создания структуры:
- по интерфейсу,
- по процессам.

1️⃣По интерфейсу

Наиболее простой вариант структуры. В нём разделы документации повторяют разделы в интерфейсе. Например:
- Мой кошелек
- Операции
- Сбережения
- История.
Когда подходит: когда продукт небольшой и простой.
Чтобы документация не скатилась к пересказу интерфейса, дополните описание кейсовыми статьями - расскажите, как с помощью продукта решить конкретные задачи.

2️⃣По процессам

Более сложный вариант, требует полного погружения в продукт. Структура выстраивается от начала использования, простого старта до сложных настроек. При этом описываются объекты системы, их классификация, их взаимодействие, а также пользователи, их роли и права.
Только так описываются сложные продукты и системы, примерно такого описания требует ГОСТ.
Как может выглядеть структура:
- О продукте
- Подключение
- Быстрый старт
- Панель администратора (как попасть, все объекты, права, роли, настройки, процесс)
- Пространство пользователя (как попасть, доступные настройки и работа с продуктом)
- Интеграции или API
- Решение проблем или частые вопросы.

🔆А теперь - задание

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

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

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

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

#циталити
Автор цитаты — Арина Балерина

Всем привет!
Нас зовут Лида, Маша и Катя, и мы технические писатели)

Этот пост — навигатор по каналу. Переходите по тегам и читайте то, что вам нужно.

#начало — информация о том, с чего начать.
#колонкаредактора — наши мысли о проблемах профессии. (а тут - грейды)
#выпуск — пошаговый путь в технические писатели. Мы нумеруем выпуски по порядку.
#такбывает — истории из практики.
#вопросвлоб — разбираем частые вопросы, которые звучат на собеседованиях.
#какэтоработает — рассказываем о рабочих процессах.
#практика — практические задания. Помечаем дополнительными тегами, чтобы обозначить область документации.
#пользовательскоеписалити — публикации о создании пользовательской документации.
#личныйОпыт — рассказываем, как сами преодолевали какие-то трудности.
#писалитирекомендует — лучшие практики, методологии или приёмы.
#циталити — полезные цитаты опытных техписателей.
#мемница — рубрика с мемами. Новые знания откроют для вас целый пласт профессионального юмора.
#невыдуманныеистории — интерактивная игра, как устроиться и начать работать техническим писателем.
#средаразработки — рассказываем о терминах в IT, с которыми может столкнуться технический писатель.
#предложка — отвечаем на ваши вопросы.

Впереди ещё много тем и новых рубрик. Учитесь с нами)

#вопросвлоб
Продолжаем разбирать вопросы из собеседований.
Итак, вопрос, который вам зададут с вероятностью в 99,9%:

Почему решили уйти с предыдущего места работы?

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

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

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

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

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

Готовьте свой ответ заранее. Это поможет вам быть убедительным и частично избавиться от стресса.

Всем привет! Это сообщение для опытных коллег)

Костя Медведев вчера всполошил весь телеграм - зовёт в спикеры мегакрутой конференции😉. Для тех, кто не в курсе, и для тех, кто еще не принял решение:

30 ноября и 1 декабря пройдёт конференция по управлению знаниями

🔆KnowledgeConf 2023!

Обычно мы слушаем и смотрим про сбор, анализ и использование ценных для бизнеса знаний. Но сегодня предлагаем другое)

🔸Станьте спикером конференции!

Почему мы поддерживаем Костю и KnowledgeConf 2023?

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

💚Понимать ценность своей работы и уметь о ней рассказывать.

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

подавайте доклад здесь: 👉 https://cfp.knowledgeconf.ru/
Там же можно прочитать про сроки, этапы, подробности, условия и всякие плюшки спикерам.

Если есть вопросы или нужна дополнительная информация, смело пишите руководителю Программного комитета Косте Медведеву: @medvedevkonstanteen.

Вперед!❤️

#колонкаредактора
Всем привет!
Мы подготовили пост на важную тему Сколько я стою на рынке труда. Но потом перечитали и поняли, что его можно заменить одной фразой: полистайте hh.ru😏

Поэтому вместо этого поста лучше поделимся, что нам помогает оценивать себя:

- Общение с друзьями-техписами на тему зп,
- Общение в профессиональных сообществах,
- Просмотр того же hh.ru и аналогов,
- Анализ собственной работы,
- Как ни странно - собеседования.

А чтобы вы не подумали, что мы вас обманываем и что мы на самом деле не писали пост, мы оставим его в комментариях.

#колонкаредактора #грейды
Грейдер технических писателей по версии школы Техписалити!

#колонкаредакторов
Всем привет! Сегодня у нас важная тема:

Грейды технических писателей

Как определить своё место в мире документации, построить путь развития или обосновать повышение зарплаты? Конечно, это можно сделать с помощью анализа своих знаний и умений.

Как правило, в крупных компаниях есть свои грейды технических писателей. Эти грейды учитывают специфику предметной области и стека технологий. Но что делать, если человек еще не работает в такой компании?

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

Можно ли быть синьором, не зная XML? Да, например, если вы работаете с ГОСТ.
Можно ли, умея писать скрипты на Python, не быть синьором? Да, если вы не способны построить структуру документации.

Мы собрали свой опыт, опыт друзей-техписателей, информацию из других грейдеров и грейдеров смежных областей и подготовили свой упрощенный и унифицированный список грейдов школы Техписалити!

Но это еще не всё)

Мы приглашаем каждого из вас к разработке общего грейдера. Переходите по ссылке и оставляйте комментарии под постом или в этом документе.

#какэтоработает
Всем привет! А вы замечали, что прежде чем читать, мы сканируем текст? Заголовки, врезки, схемы, картинки, иконки - всё это точки внимания, которые проводят нас по статье.
Задача технического писателя - создать статью, которая приносила бы пользу даже при сканировании, а не только при чтении.

Мы в команде придерживались простых правил в статьях.

1️⃣ Подзаголовки должны отвечать на условный вопрос заголовка. Например:

Как настроить схему работы (заголовок)
- Создайте статусы (подзаголовок)
- Создайте переходы (подзаголовок)
- Настройте правила переходов (подзаголовок).

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

2️⃣ Выделить много - не выделить ничего. Хрестоматийное правило требует аккуратно выбирать визуальные якори. Если выделить мало не получается, например, в тексте часто упоминаются элементы интерфейса, используйте списки или схемы.

3️⃣ Каждому элементу - свой стиль. Если вы используете полужирное начертание, делайте это осознанно. Например, выделяйте только элементы интерфейса. Если вы хотите выделить какую-то мысль, используйте режим примечания. Не забывайте, что слишком выделенный элемент мозг отсекает, как назойливый рекламный макет. Не старайтесь выделить все, помните о правиле №2.

Тестируйте статьи на себе и коллегах при ревью.

#какэтоработает
Всем привет! Вы написали документацию и проверили её с точки зрения языка и стиля. Что происходит дальше?

Тестирование документации

Любую документацию нужно проверить: не вводит ли она пользователей в заблуждение?

🔸Как в идеальном мире

В крупных компаниях тестировать документацию иногда привлекают тестировщиков. Они смотрят и техническую, и пользовательскую часть. Если есть ошибки, тестировщики создают задачи на их исправление или оставляют комментарии к статье.

🔸Как чаще всего

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

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

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

Помните: если у пользователя будет шанс ошибиться, он ошибётся. Не жалейте своих формулировок, исправляйте, если сомневаетесь в них.

Вычитайте текст снова, избавьтесь от возможных опечаток и ошибок.

Когда документация проверена, публикуйте её. Заканчивается ли на этом её тестирование? Конечно, нет. Встречали в мемах формулировку тестирование на пользователях? Так вот, это не совсем мем.

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