👀 На просторах ЛинкедИна набрел на отличный пост Daria Shatsylo про то, почему из команды уходят техписы. ИМХО, довольно реалистичный взгляд на вещи. Как четко подметили в комментариях, можно смело брать статью и кидать своим ПМ’ам.

Предисловие:

Наличие технического писателя в команде воспринимается либо как нечто само собой разумеющееся, либо как нечто вызывающее вопросы “Ты кто? Ты что тут делаешь?”.

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

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

Почему же такой человек в один прекрасный день может взять и уйти?

🔗 Читать: Почему из команды уходит техписатель? У меня на это 5 причин

Бонус-P.S:

🔗 Читать: 14 Ways to Make a Good Technical Writer Quit

#career #ru

В Google Docs готовится что-то крутое

https://twitter.com/GoogleWorkspace/status/1394703393600544771?s=19

#tool #en

Всем привет!

Иксолла открыла прием заявок на направление Documentation в рамках Xsolla School 2021!

В этом году впервые организовано два потока:

– Базовый (количество участников не ограничено): для тех, кто хочет познакомиться с основными понятиями и принципами документации.

– Профильный (только 15 участников): для тех, кто уже знает основы работы с документацией и хочет прокачать профессиональные навыки.

На школе вы научитесь писать документацию, которую реально будут читать, начнете понимать особенности ГОСТов и стайлгайдов, узнаете специфику подготовки контента для UI/UX веб-приложений и многое другое!

Обучение в школе полностью бесплатное. Прочитать подробности и пройти регистрацию можно по ссылке: https://rb.gy/wftbg5

Если вы только начали открывать для себя линтеры простого нашего с вами языка, то предлагаю к ознакомлению отличный интродакшн в Vale.

Объясняют и в чем отличие от линтеров кода, и этимологию самого слова, и даже делятся ссылочкой на Vale Studio, которой я совсем забыл с вами поделиться. Vale Studio это бесплатный веб-бейзд редактор, который позволяет легко создавать и тестировать новые правила. Очень тесно интегрирован с regex101.

🔗 Читать: First steps with the Vale prose linter

#tool #testthedocs #en #article

Иногда нужно быстро “поиграться текстом” на уже запаблишеном материале, будь-то заголовок, подзаголовок или какая-то сноска. Что мы все делаем обычно в таком случае? Конечно же, идем в ДевТулзы браузера и ковыряем буквы там. Но, скажем честно, процесс не самый магический и завораживающий, поэтому от него хотелось бы отказаться в пользу чего-нить поудобнеé.

Наткнулся на приятный плагинчик для (извините пользователи Firefox) Chromium-based браузеров, который превращает любой текст в готовый для редактирования

Пользуйтесь на здоровье: Polishapp 💅

#tool #visual #en

Стоит ли использовать в документации обращение от первого лица множественного числа?

Наверняка во время написания технической документации, у вас возникала мысль использовать: “we”, “us”, и “ours”. Но в отличие от второго лица (“you”), использование “we” не так явно распространено или приемлемо.

Но не все так просто! Статья углубляется в вопрос использования “we” и кроме того, автор сравнивает как разные стайлгайды советуют поступать с вот этим вот всем.

🔗 Читать: Should you use the first-person plural in your documentation?

#language #en

💡Мечтать не вредно, но и вредно не мечтать, или сказ об идеальных митингах.

Недавно я выкладывал пост про “Амазоновский Шестистраничник” (звучит как что-то из урбандикшнари, да), а теперь пришло время еще немного расширить границы познания о культуре документации в Amazon, ибо она крутая.

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

И в чем же секрет, спросите вы? Конечно же в чтении документации! Но ее и так читают, скажете вы? Как бы не так! Но тут речь идет о >document-based-митингах<, начинаются которые с (нет, вы только представьте) коллективного чтения документа.

В чем автор поста видит проблему обычных митингов:

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

Несмотря на гору плюсов, выделять от 10 минут до получаса только на чтение документа, а в случае с шестистраничником, так и еще больше, может позволить себе далеко не каждая команда/компания. Но с другой стороны, к митингам можно больше не готовиться. 🤷

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

И запомните, if there isn’t a doc there isn’t a meeting

🔗 Читать: The Document Culture of Amazon

#article #en

Notion запустил Synced Blocks!

Вместо того, чтобы обновлять один и тот же кусок документа в миллионе мест, теперь можно создать Synced Block и ссылаться на него в любом другом месте, а изменения подтянутся :3

P.S

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

#tool #en

Люблю честные чейнджлоги ❤️

#changelog #en

💰 Подъехали результаты опроса по зарплатам Техписателей за 2020 год.

🔗 Читать: Write the Docs Salary Survey 2020 Results

#career #en

Kathy Korevec, Продукт Манагер из GitHub, написала занимательнейшую статью с просто горооой размышлений о том, как улучшить документацию в GitHub. Кроме того, она нагенерировала еще ведро идей о том, как оптимизировать документацию для разработчиков, и подкрепила их мокапами. Говорит о необходимости “многоформатности” документации, об оптимизации поиска, в общем очень интересный взгляд внутрь головы продукт манагера довольно таки большой компании, рекомендуется к прочтению.

🔗Читать: Maybe it’s time we re-think docs

#article #en

И мы плавно возвращаемся из отпуска! Stay tuned..накопилось много годноты.

Да, иногда даже на Хабре бывает полезный и читабельный контент.

Kiii~nda саксесс стори с (пере)построением базы знаний, которая действительно работает и выполняет свои задачи, а еще все это дело в Notion.

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

Ждем продолжение, ну а пока, всем хорошего старта рабочей недели 🙏

🔗 Читать: Как (не) нужно строить базу знаний для проекта с нуля. Часть Первая, утопическая

#knowledgemanagement #ru #article

🔥 Небольшой мотивационный пост, приуроченный к красивому числу подписчиков!

Спасибо, что вы есть 😘

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

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

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

И помните, it doesn’t matter how great your software is if nobody understands how or why they should use it 👆

🔗 Читать: The uber-importance of docs

#article #en

При сравнении продуктов, вы хотите понять, какой все же из них лучше? Тем не менее мы часто забываем оценить документацию по проекту. Проект может предлагать отличный набор функций, но в то же время у него может не быть простой в использовании документации. Это может отрицательно сказаться на процессе использования продукта и эффективности вашей команды. Автор статьи предлагает, пусть и без откровений, научиться оценивать UX документации (со стороны разработчиков).

🔗 Читать: Developer Experience: How to Define Good Documentation?

#article #en

Немного апдейтов из мира стайлгайдов:

1. Google обновил часть своего стайлгайда про заголовки.
2. GitHub добавили раздел с правилами по написанию гендерно-нейтральной документации в свои гайдлайны.

#styleguide #en