An Honest Review of Gatsby

Статья в которой автор(ы) Sentry (мониторинговая платформа для разработчиков) рассказывают о своем опыте переезда с Jekyll на Gatsby. Интересно посмотреть, как на действительно большом и не самом простом проекте на самом деле работает Гетсби (hint: все не так радужно, как могло казаться). Главный пойнт в том, что статик сайт генератор не должен быть настолько сложным, что работа с MDX не так простá как это пытаются показать и что GraphQL не особо-то и нужен в SSG.

Если у вас были мысли о переводе вашей документации на Gatsby, настоятельно советую ознакомиться, там и про тот же GraphQL, и про не самую полную документацию. Всё не плохо, но достаточно проблематично, чтобы смочь в это всё с наскока, а люди в Sentry уже имели опыт, но все еще столкнулись с большим количеством (не)решаемых проблем.

#SSG #en

В подкасте я упоминал про историю Технического Писательства, про вторую мировую и всякое такое. Тут можно узнать об этом всем и о многом другом поподробнее.

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

В чем суть?

Статья называется "Whatever Happened to Technical Writing", авторства Elizabeth Tebeaux, преподавателя Технического Письма с 40 летним(!) стажем.

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

Материл - бомба. Очень советую.

#book #article #career

Пост сразу и для работодателей и для техписов.

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

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

http://stcrmc.org/wordpress/?p=2968

#career #vacancy #en

Хорошие новости для пользователей oXygen XML Editor!

Начата работа по внедрению нативной поддержки Vale. Теперь следовать стайлгайдам будет проще

https://twitter.com/radu_coravu/status/1314460946417487873

#testthedocs #tool #en

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

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

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

Это видеоподкасты в двух частях и одной текстовой:

Часть 1
Часть 2
Часть 3
Текстовая версия

#DocsAsCode #en #article

Не умеешь/не привык начинать с пустого листа? Застрял после первого предложения? Попробуй заставить Машин Лернинг (GPT-2) набросать идей!

Раньше я сам иногда пользовался Talk to Transformer, но он как-то совсем не очень. А сейчас наткнулся на writeup.ai и прям небо и земля.

Если где-то есть на пощупать что-то похожее но с GPT-3 — дайте знать в комментах.

#language #ai #en

Daily Reminder:

Содержите вашу документацию “доступной” для людей с ограниченными возможностями.

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

#accessibility #checklist #en

И почитать что там у других:

1. Небольшая выжимка из наблюдений на WriteTheDocs
2. Более подробный разбор старых статистик и немного более свежей инфы

#career #en #article

Уже доступны видео с докладами и лайтнин толками Write the Docs Prague 2020!

Отдельно почитать про что каждый из докладов можно на официальном сайте WTD.

enjoy!


1. Mikey Ariel - Introduction to Prague 2020
2. Kruno Golubić - From Graffiti Writer to Technical Writer
3. Abigail Sutherland - Organizing a Confluence hoard, or, does this page spark joy?
4. Natali Vlatko - Documenting the (Ancient) History of Your Project
5. [Lightning Talk] Kenzie Woodbridge - Affective Data Visualization (CW)
6. [Lightning Talk] Fabrizio Ferri Benedetti - Be a Salmon
7. [Lightning Talk] Wouter Veeken - "Should I move to Japan?" -- Advice for my past self
8. Paul Brown - The Baseline -- Or Technical Writing for Non Technical Readers
9. Karen Sawrey - Remote Job On boarding: Top 10 Things We Can Do Better
10. Myriam Jessier - Making documentation discoverable in search engines
11. Andrew Haynes - A Journey to Pattern Languages
12. Matt Reiner - Bake a Little Documentation Love into Your Product
13. Karissa Van Baulen - The Importance of Using Analytics and Feedback for your Documentation
14. Diana Lakatos - Helping Your Community Contribute to Developer Documentation
15. Chris Noonan - The Rocky Road to DocOps
16. Tanks Transfeld - Emulating the Teacher's Approving Nod in Teaching Material
17. [Lightning Talk] Bart Buerman - Running a conference livestream from my living room
18. [Lightning Talk] Emily Axel - Conveying Emotion Over Slack: A Tale of Two Emojis
19. [Lightning Talk] Tina Lüdtke - A quick round trip inside the brain
20. [Lightning Talk] Shweta Naresh - Technical writers or UX advocates
21. [Lightning Talk] Surya Panneer - Technical Editing Checklist
22. Jessica Valasek Estenssoro and Arthur D'Herbemont - How to be an Avante-Garde Guinea Pig
23. Joe Malin - Need Examples? Write Your Own!
24. Jen Weaver - Future-Proofing Your Support Visuals
25. Ingrid K Towey - When Wishing Still Helped... What Folklore Can Teach Us About Technical Writing

#conference #video #en #resource #article

Vale теперь и в вебе!

Теперь для того, чтобы проверить ваш текст на соответствие с стайлгайдом (пока что Microsoft, Vale, и Write Good прибиты гвоздями, но скоро можно будет пользовать свои) не нужно настраивать ни CI, ни плагин для VS Code, теперь можно просто скормить сервису вебстранчку!

Doculint

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

#testthedocs #en #tool

Поговорим про развитие?

Как вы видите свое будущее? Поделитесь своими намеченными ветками прокачки.

Кто что планирует вкачивать, станете ли вы UX-писателем, вкините ли пару очков опыта в DocOps и будете двигаться в сторону автоматизации? Или вам больше по душе стать Бизнес Аналитиком, который будет собирать требования к продукту и грамотно их формулировать. Есть ли на вашей работе песпективы стать кем-то кроме писателя?

Для упрощения раздумий делюсь с вами несколькими статьями и, как по мне, довольно неплохой схемой с вариантами развития (картинка приаттачена к посту).

1. Models for Personal Growth: Career Progression for Tech Writers (презентация)

2. After Tech Writing: Where Do You Go If You Want To Move On?

Если у вас завалялись матрицы навыков или диаграммы, аналогичные той, что в шапке поста, и все это дело не под строгим NDA — поделитесь, будьте добры, комментарии открыты

#career #en #resource #article

Пятничка! 💫

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

Сегодня у нас в эфире инструкции к самой обсуждаемой железке конца 2020го года. Это то, с чем нам прийдется жить и на что смотреть изо дня в день ближайшие 4-7 лет, PlayStation 5!

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

Enjoy :}

Recommended settings:
https://youtube.com/watch?v=eMRsCR68tgQ

Using your account:
https://youtube.com/watch?v=H2DqsPh2d9k

Transfer files from PS4 to PS5:
https://youtube.com/watch?v=V8cmLeFQBT0

#example #video #visual

Vale отлично справляется с md и adoc файлами, но что если у вас Swagger API дока, которая не хавается нативно линтером?

Vale & The OpenAPI Specification поможет разобраться именно в этом. API доки такие же доки как гайды и хау-ту, держите их в чистоте и порядке, и да будут ваши юзеры благодарны!

#asciidoc #markdown #testthedocs #en #tool

Что такое плохая документация? Каково пользоваться плохо задокументированным продуктом?

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

Я однажды приводил документацию Apple как хороший визуальный образец, но, как оказалось, хороша она в основном только визуально и отвечает только на базовые вопросы и показывает как работают самые простые сценарии. Если же сделать шаг влево или вправо, получается “it’s like you’re jumping off this cliff, and it’s like “good luck”. […]”

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

Если у вас есть примеры плохой документации хороших продуктов — велкам ту коммент секшн. Делитесь, жалуйтесь ну и всякое такое :}

#example #en #article

Шаблоны документации найти непросто, а хорошие шаблоны найти почти нереально.

Поэтому особенно пристально предлагаю ознакомиться с подборкой шаблонов (в Notion) на ВСЕ случаи жизни от Air!

#example #en #resource

Небольшое, можно сказать, продолжение истории от Spotify про их Backstage и TechDocs плагин для него (не так давно как раз писал про это).

О чем?

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

Автор даёт 10 советов о том, как строить долгосрочные отношения с docs-as-a-code подходом, учит смотреть в будущее, как решать возникающие по ходу дела проблемы и рассказывает как смотреть на правильные метрики.

Читать

#DocsAsCode #tool #en

Наткнулся на на очередной инклюзивной писанины пост и подумалось мне, что это примерно то же самое, что я читал в предыдущей сотне статей про inclusive language.

Редакторскому составу этого блога данная тема кажется неинтересной и довольно простой, пускай она сейчас и актуальна 🏳️‍🌈 . Вот список слов которые обижают людей в 2020 году, вот список слов которыми их заменить, ну и как бы на этом все. 🤷

Собственно вопрос, постить что-то по этой теме или нет?

#accessibility #en #article

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

> In the end, you can’t generate documentation from code. You can generate formatting and layout, and infer some structure, but you still have to write the content. You can’t express all of the content you need in code, and you can’t write good documentation the way you write code. You should probably hire a technical writer instead.

Читать

#resource #en #article