Vale теперь и в вебе!
Теперь для того, чтобы проверить ваш текст на соответствие с стайлгайдом (пока что Microsoft, Vale, и Write Good прибиты гвоздями, но скоро можно будет пользовать свои) не нужно настраивать ни CI, ни плагин для VS Code, теперь можно просто скормить сервису вебстранчку!
Doculint
Сервис пока находится на стадии бета-тестирования и требует некоторой шлифовки напильничком, но движение в правильном направлении уже есть. Пример подробного отчета на скрине к посту :}
#testthedocs #en #tool
Теперь для того, чтобы проверить ваш текст на соответствие с стайлгайдом (пока что 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
Как вы видите свое будущее? Поделитесь своими намеченными ветками прокачки.
Кто что планирует вкачивать, станете ли вы 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
В преддверии выходных можно слегка расслабиться и посмотреть как делают документацию другие.
Сегодня у нас в эфире инструкции к самой обсуждаемой железке конца 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
YouTube
PS5 - Recommended Settings
0:00 Introduction
0:19 Sound Settings & 3D Audio
0:58 Haptic Feedback & Trigger Sensitivity
1:21 Power Saving Settings
1:47 Automatic System Software Updates
2:00 Turn On Console Remotely
2:15 Enabling Remote Play
2:19 Automatic Updates for Games & Apps
…
0:19 Sound Settings & 3D Audio
0:58 Haptic Feedback & Trigger Sensitivity
1:21 Power Saving Settings
1:47 Automatic System Software Updates
2:00 Turn On Console Remotely
2:15 Enabling Remote Play
2:19 Automatic Updates for Games & Apps
…
Vale отлично справляется с md и adoc файлами, но что если у вас Swagger API дока, которая не хавается нативно линтером?
Vale & The OpenAPI Specification поможет разобраться именно в этом. API доки такие же доки как гайды и хау-ту, держите их в чистоте и порядке, и да будут ваши юзеры благодарны!
#asciidoc #markdown #testthedocs #en #tool
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
Почитайте как выглядит настоящая боль от плохой документации.
Я однажды приводил документацию Apple как хороший визуальный образец, но, как оказалось, хороша она в основном только визуально и отвечает только на базовые вопросы и показывает как работают самые простые сценарии. Если же сделать шаг влево или вправо, получается “it’s like you’re jumping off this cliff, and it’s like “good luck”. […]”
Оказывается, документация настолько плохая, что она стала своеобразным мемом, который даже родил целый сайт, который сквозь слезы потешается над убогостью док.
Если у вас есть примеры плохой документации хороших продуктов — велкам ту коммент секшн. Делитесь, жалуйтесь ну и всякое такое :}
#example #en #article
Небольшое, можно сказать, продолжение истории от Spotify про их Backstage и TechDocs плагин для него (не так давно как раз писал про это).
О чем?
О том, что казалось бы, сделав годную платформу для документации, можно было бы и расслабиться, но нет.
Автор даёт 10 советов о том, как строить долгосрочные отношения с docs-as-a-code подходом, учит смотреть в будущее, как решать возникающие по ходу дела проблемы и рассказывает как смотреть на правильные метрики.
Читать
#DocsAsCode #tool #en
О чем?
О том, что казалось бы, сделав годную платформу для документации, можно было бы и расслабиться, но нет.
Автор даёт 10 советов о том, как строить долгосрочные отношения с docs-as-a-code подходом, учит смотреть в будущее, как решать возникающие по ходу дела проблемы и рассказывает как смотреть на правильные метрики.
Читать
#DocsAsCode #tool #en
Наткнулся на на очередной инклюзивной писанины пост и подумалось мне, что это примерно то же самое, что я читал в предыдущей сотне статей про inclusive language.
Редакторскому составу этого блога данная тема кажется неинтересной и довольно простой, пускай она сейчас и актуальна 🏳️🌈 . Вот список слов которые обижают людей в 2020 году, вот список слов которыми их заменить, ну и как бы на этом все. 🤷
Собственно вопрос, постить что-то по этой теме или нет?
#accessibility #en #article
Редакторскому составу этого блога данная тема кажется неинтересной и довольно простой, пускай она сейчас и актуальна 🏳️🌈 . Вот список слов которые обижают людей в 2020 году, вот список слов которыми их заменить, ну и как бы на этом все. 🤷
Собственно вопрос, постить что-то по этой теме или нет?
#accessibility #en #article
Linkedin
Ashleigh Rentz on LinkedIn: Inclusive language | 27 comments
As a tech writer, words matter a lot to me. They convey meanings, both intended and sometimes not. Inclusive language is an approach to considering what our… | 27 comments on LinkedIn
Небольшая статейка о написании документации с точки зрения разработчика, с размышлениями о том, почему у них (разработчиков) не всегда выходит писать качественную документацию.
> 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
> 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
Извините за задержку в постах, у главреда заболел кошак, пока животинка полноценно не излечится, скорость постов немного снизится.
Но не сегодня!
Сегодня у нас ❗️пятничный пост❗️ Пост об аудитории, о работе с ней, и кроме того, мы немножко макнём свои лапки в пучину истории.
———
Как я когда-то писал (в посте про Гелиограф), я очень люблю военную/армейскую документацию, ведь в ней нет ничего лишнего, она лаконична, прямолинейна и идеально работает с аудиторией (еще один мой пост про (kinda) военные доки.) В сегодняшнем посте - очередной пример такой документации.
———> (с) Highlights for Warspot: from the best angle
#vintage #visual #en
Но не сегодня!
Сегодня у нас ❗️пятничный пост❗️ Пост об аудитории, о работе с ней, и кроме того, мы немножко макнём свои лапки в пучину истории.
———
Как я когда-то писал (в посте про Гелиограф), я очень люблю военную/армейскую документацию, ведь в ней нет ничего лишнего, она лаконична, прямолинейна и идеально работает с аудиторией (еще один мой пост про (kinda) военные доки.) В сегодняшнем посте - очередной пример такой документации.
———> (с) Highlights for Warspot: from the best angle
#vintage #visual #en
“Солдаты ничем не отличаются от детей, если верить шутливой и не очень приличной поговорке. В этом не было ничего плохого, пока военные были вооружены несложным оружием и использовали примитивную тактику, однако взрослым детям доверяли все более сложное вооружение, технику и обучали различным приемам по мере развития войны. С изобретением книгопечатания в игру вступили справочники и руководства пользователя, и внезапно выяснилось, что солдаты не любят читать скучные книги с мелкими шрифтами.
В конце концов было решено превратить обучение солдат в увлекательную игру.
Таким образом, Вторая мировая война принесла с собой целую часть учебной военной литературы с комиксами, наполненными девочками и анекдотами. Немцы превзошли самих себя - в Германии в полушутливой форме были опубликованы
инструкции по эксплуатации «Тигра» и «Пантеры», руководства, в которых учились десятки забавных способов уничтожения советских танков и объяснения для пилотов Люфтваффе, как вести движущуюся цель, чтобы сбить Спитфайр.”
#vintage #visual #en
В конце концов было решено превратить обучение солдат в увлекательную игру.
Таким образом, Вторая мировая война принесла с собой целую часть учебной военной литературы с комиксами, наполненными девочками и анекдотами. Немцы превзошли самих себя - в Германии в полушутливой форме были опубликованы
инструкции по эксплуатации «Тигра» и «Пантеры», руководства, в которых учились десятки забавных способов уничтожения советских танков и объяснения для пилотов Люфтваффе, как вести движущуюся цель, чтобы сбить Спитфайр.”
#vintage #visual #en
Причины менять интерфейсный текст могут быть очень, очень разные
https://twitter.com/MichaelSteeber/status/1334619509743874052?s=20
#example #uiux
https://twitter.com/MichaelSteeber/status/1334619509743874052?s=20
#example #uiux
Twitter
M1 battery life is so good that the macOS UX writers will need to redefine “soon”
Начало недели, не очень хочется нагружать и себя, и вас чем-то совсем уж узкопрофильным, поэтому предлагаю слегка отвлечься и почитать небольшую историю о создании своего собественного статик сайт генератора, и о важности личных пет-проджектов.
Читать: Why I Built My Own Shitty Static Site Generator
Bonus Track: Микро-история про создание спеллчекера в 84 году (хотя больше про стремительный прогресс технологий)
#SSG #DocsAsCode #en #testthedocs
Читать: Why I Built My Own Shitty Static Site Generator
Bonus Track: Микро-история про создание спеллчекера в 84 году (хотя больше про стремительный прогресс технологий)
#SSG #DocsAsCode #en #testthedocs
Если вы утомились от бесконечных блогпостов, чтения чатиков и комментариев в LinkedIn/Telegram/Slack и хочется простого человеческого почитать книгу, то предлагаю вам подборочку книг по нашему с вами профилю.
Feel free делиться своими любимыми книженциями в комментариях 🙌
Смотреть подборку
#book #en
Feel free делиться своими любимыми книженциями в комментариях 🙌
Смотреть подборку
#book #en
Ноушн запускает доступ к API.
Готовимся к полному завоеванию Ноушном всего мира knowledge-sharing'а
https://www.notion.so/api-beta
#API #knowledgemanagement
Готовимся к полному завоеванию Ноушном всего мира knowledge-sharing'а
https://www.notion.so/api-beta
#API #knowledgemanagement
Notion
Start building with the Notion API
Connect Notion pages and databases to the tools you use every day, creating powerful workflows.
Не Ctrl-F’ом единым.
Статья о DocSearch от Algolia, лучшего поставщика поиска для приложений и сайтов.
Algolia привидит следующие пункты в пользу полноценного поиска, вместо обычного Ctrl+F, к которому так привыкли все:
1️⃣ Поиск по всему сайту документации, а не только по одной загруженной странице.
2️⃣ Допуск опечаток. Наш поиск исправляет неверные запросы и опечатки. Это ключевой момент при поиске неизвестных концепций или технологий.
3️⃣ Алгоритм разрыва связи. Эта уникальная концепция Algolia помогает мейнтейнеру лучше перенаправлять пользователей, помогая им в интерактивном режиме. Меньше необходимости в поддержке!
4️⃣ Аналитика. Наш поиск поможет вам понять, что делают ваши пользователи.
(больще - внутри статьи, все не влезло ↩️)
В статье никаких откровений, просто даю вам знать (если вы не знали) что есть такая клёвая и 💴 бесплатная 💴 тулза, и избавить вас от изобретения очередного велосипеда или если вас не устраивает условный lunr.js
Читать о DocSearch
#article #en
Статья о DocSearch от Algolia, лучшего поставщика поиска для приложений и сайтов.
Algolia привидит следующие пункты в пользу полноценного поиска, вместо обычного Ctrl+F, к которому так привыкли все:
1️⃣ Поиск по всему сайту документации, а не только по одной загруженной странице.
2️⃣ Допуск опечаток. Наш поиск исправляет неверные запросы и опечатки. Это ключевой момент при поиске неизвестных концепций или технологий.
3️⃣ Алгоритм разрыва связи. Эта уникальная концепция Algolia помогает мейнтейнеру лучше перенаправлять пользователей, помогая им в интерактивном режиме. Меньше необходимости в поддержке!
4️⃣ Аналитика. Наш поиск поможет вам понять, что делают ваши пользователи.
(больще - внутри статьи, все не влезло ↩️)
В статье никаких откровений, просто даю вам знать (если вы не знали) что есть такая клёвая и 💴 бесплатная 💴 тулза, и избавить вас от изобретения очередного велосипеда или если вас не устраивает условный lunr.js
Читать о DocSearch
#article #en
В последнее время вижу все больше и больше пользователей и советчиков (и без того популярного) MkDocs, поэтому вот вам два гайда, которые might come in handy на старте, так сказать:
1. Getting started with Material MkDocs — установка, кастомизация, публикация и траблшутинг.
2. Deploying MkDocs with Material theme to Netlify — название говорит само за себя
#markdown #DocsAsCode #SSG
1. Getting started with Material MkDocs — установка, кастомизация, публикация и траблшутинг.
2. Deploying MkDocs with Material theme to Netlify — название говорит само за себя
#markdown #DocsAsCode #SSG
Why Free Software needs Free Documentation
—————————
Самый большой недостаток бесплатных операционных систем заключается не в программном обеспечении, а в отсутствии хороших бесплатных руководств, которые могли бы поставляться с этими системами. Многие из наших наиболее важных программ не поставляются с полными руководствами. Документация - неотъемлемая часть любого программного пакета; когда к важному пакету бесплатных программ не прилагается бесплатное руководство, это серьезный пробел. Сегодня у нас много таких пробелов.
—————————
Статья рассматривает проблемы проприетарных (не _ПЛАТНЫХ_) руководств и как всегда у GNU — про ущемление свобод.
Читать.
#article #en
—————————
Самый большой недостаток бесплатных операционных систем заключается не в программном обеспечении, а в отсутствии хороших бесплатных руководств, которые могли бы поставляться с этими системами. Многие из наших наиболее важных программ не поставляются с полными руководствами. Документация - неотъемлемая часть любого программного пакета; когда к важному пакету бесплатных программ не прилагается бесплатное руководство, это серьезный пробел. Сегодня у нас много таких пробелов.
—————————
Статья рассматривает проблемы проприетарных (не _ПЛАТНЫХ_) руководств и как всегда у GNU — про ущемление свобод.
Читать.
#article #en