Ноушн запускает доступ к API.

Готовимся к полному завоеванию Ноушном всего мира knowledge-sharing'а

https://www.notion.so/api-beta

#API #knowledgemanagement

Не Ctrl-F’ом единым.

Статья о 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

Why Free Software needs Free Documentation

—————————

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

—————————

Статья рассматривает проблемы проприетарных (не _ПЛАТНЫХ_) руководств и как всегда у GNU — про ущемление свобод.

Читать.

#article #en

Посыпаю голову пеплом, но только под конец 2020го узнал о Nielsen Norman Group.

Кто это такие?

NN/g — исследовательская и консалтинговая UX компания, которой доверяют ведущие организации по всему миру, среди клиентов NN: Google, Visa, Verizon, Sony, eBay (хотя UX ибэя по прежнему наводит страх и ужас, но может какой-то другой их проект), National Geographic и другие мастодонты индустрии.

Основатели — Якоб Нильсен и Дон Норман, признанные во всем мире эксперты в области UX. Вместе они основали Nielsen Norman Group, элитную фирму, стремящуюся улучшить повседневный опыт использования технологий.

Дон Норман
Автор книги «Дизайн повседневных вещей», также он придумал и популяризировал термин «UX» на заре работы в Apple. Дон Норман был признан Newsweek «Guru of Workable Technology».

Якоб Нильсен
Автор юзабилити-чеклиста “10 Usability Heuristics” и один из первых поборников юзабилити-тестирования. Якоб Нильсен был признан «Guru of Usable Web Pages» газетой New York Times.

Скачать “10 Usability Heuristics” можно по ссылкам ниже, а можно и почитать. 🤓

⬇️Downloads⬇️
Jakob's 10 Usability Heuristics All Posters (ZIP)
Jakob's 10 Usability Heuristics Summary Poster (PDF)
Jakob's 10 Usability Heuristics Summary Poster, A4 Size (PDF)
Jakob's 10 Usability Heuristics Summary Poster, Letter Size (PDF)

Сегодня хочу обратить ваше внимание на 10-й пункт в чеклисте - Help and Documentation

Help and Documentation: The 10th Usability Heuristic

—————————

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

Читать.

#resource #article #en

Я уже делал много постов про комиксы, так как они очень дороги сердцам всего редакторского состава и не могу обойти стороной новый комикс-гайд. В этот раз про Bash.

Прошлые комиксы в основом были от Джулии Эванс, как и вот этот вот. Она просто мастер простого и понятного визуального изложения совсем уж сложных вещей (кубернетесы, контейнеры, сеть, HTTP, Linux)

Делюсь этим не в ключе “читайте этот гайд”, а в ключе “смотрите как можно”, и не просто можно, а можно прямо КРУТО.

Bite Size Bash!

P.S:

При покупке обратите внимание на месседж под кнопкой покупки:

>Hello! It looks like you're in Ukraine, where this zine might be expensive.
>If you need it, please use this link to get 70% off the regular price.

🧡💴

#visual #example #en

Я уже поднимал тему того, как GPT-2/3 могут помочь в нашей с вами работе. Так вот, кто-то решил возвести всё это дело в абсолют и создает специализированный сервис, который поможет найти вдохновение, и подобрать слова, когда “не идёт“. Пока что с GPT-2 и небольшим датасетом, но начало уже положено, и планы на GPT-3 уже намечены.

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

Похоже, скоро от писательского блока не останется и следа!

Посмотреть что там с AiToWrite

#tool #ai #en

Посоветовавшись и оценив свою аудиторию, весь редакторский состав пришел к мнению, что нашим подписчикам итак хватает поздравлений в ругих местах, но!

🎆 Но новый год же, епта! 🎆

Учитесь новому, не стойте на месте, выходите за рамки своих “прямых обязанностей” и не бойтесь быть полезны где-то, помимо документации. Качайте креативную мышцу и всегда помните, что мы пишем не для роботов, а для людей, поэтому вкладывайте в работу душу, и другие это обязательно почувствуют 🥰.

🌲 C НАСТУПАЮЩИМ! 🌲

Интеграция VSCode и Notion

https://github.com/frencojobs/vscode-notion
Два популярных решения для работы со знаниями наконец-то можно объединить в единой среде.

У нашего главного редактора пропал нюх, но не пропал нюх на хорошие статьи про документацию! 🥁 *badum tss* 🤡 (уже все хорошо, смотрите картинку к посту)

Сегодня статья о важности Organizational Memory, о позльзе шаблонов и о пересмотре отношения к организации документации. Товарищи из Nebo признали, что чистый Agile подход к документированию (“You should only create a document if it fulfills a clear, important and immediate goal of your overall project efforts.”) эт не совсем то, что их устраивает. Было принято решение организовать группу быстрого реагирования “Great Document-Palozza” и пеерсмотреть свой подход к хранению и накоплению инженерной документации.

Спрыгнув с Agile подхода к документированию, было решено пользоватся напутствием Том Томпсона, цитируя его статью “Why agile teams should care about documentation”: “When the engineers and writers collaborate in an iterative process, they can learn from each other and make the whole process more efficient…[Moreover,] Getting technical writers involved early is a great way to get feedback on your design. If your documentation team can't figure out a feature, your customers probably won't either.” (эту статейку тоже читните, слегка базовыве вещи говорит, но, “Повторение – мать учения”!)

Получилось у них или нет — читайте в полной версии статьи How I Learned to Stop Worrying and Love Engineering Documentation

Не болейте, это скучно 🦠

#knowledgemanagement #en

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

🎤 Начнем с более свежего, с WTD подкаста.

Я уже не раз писал выражал свою любовь к SUI (Simplified User Interfaces) и сегодня как раз про это. Они там все это дело еще хитмэпами дополнили! Что может быть лучше хитмэпов c predictive eyetracking? 👀

Подкаст про упрощенную графику в скриншотах это как раз то, что нужно посреди недели.

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

Что, если бы существовал способ создания снимков экрана, который выдерживал бы быстрые итерации разрабатываемого продукта, но при этом передавал ценный смысл вашим читателям. Сегодня к нам присоединился Антон Боллен из TechSmith, который объясняет, как мы можем это сделать, используя скриншоты с низким уровнем детализации, то есть упрощенные пользовательские интерфейсы, которые позволяют вам сосредоточить внимание пользователей только на тех элементах интерфейса, которые имеют значение.”

👀 Смотреть.
👂 Слушать.

#video #en #visual

Пятничной документации пост.

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

#example #en

Очередной срез по IT зарплатам, пока ждем полноценного и более глобального разбора от Write The Docs, довольствуемся Украинской инфой.

Зарплати українських PM, HR, DevOps, Data Science та інших ІТ-спеціалістів — зима 2021

Но нас, конечно же, интересует информация исключительно по техписательству.

В этом году по причинам, которые даже не хочется уточнять, Техписов засунули в раздел с Marketing, но ничего, нам-то циферки нужны да и только.

Видим, что мы, вместе с Digital Marketing Manager имеем высшие медианы $1200. Копирайтеры попадают в — $900.

Но, выбрав диапазон опыта работы в 4-6 лет видим красивую цифру 1900 (которая у меня даже в экран не влезла), информация собрана с 13 анкет, что есть не очень репрезентативно, но уже что-то.

Так что ноги в руки и учимся-учимся-учимся 🧑‍🎓

👋🏻Немного мини-новостей на сегодня:

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

>We now recommend Docusaurus 2 as the default choice to start a new Docusaurus project and encourage v1 users to migrate to Docusaurus 2.

Посему предлагаю ознакомиться с обзором успехов Docusaurus за 2020й год

🔗Читать Docusaurus 2020 Recap

👉 Мозилла запускает Open Web Docs, инициативу по финансированию и всяческому спонсированию написания документации для таких стратегически важных ресурсов как MDN Web Docs. Цель — содержать ресурсы с документацией в активными и следить за актуальностью документации. Mozilla входит в состав Руководящего комитета OWD и помогает распределять писательский ресурс для максимальной эффективности.

🔗Почитать про анонс Open Web Docs

#SSG #article #en