Информативный пост написанный по мотивам Knowledge Conf-доклада Семёна Факторовича, руководителя documentat.io о чувстве «бесполезности» документации (и не только).

>Чаще всего за словом «бесполезна» кроется ощущение, что документация не очень хорошо выполняет свою задачу. Потому что она либо не полна, то есть описывает не все аспекты, которые хотелось бы в ней найти. Либо не точна, то есть то, что в ней написано, не полностью соответствует истине. Либо не актуальна, то есть соответствовала истине в прошлом, а сейчас программная система или внешний мир изменились, и документация перестала этому соответствовать.


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

❗️Наша редакция уважает Семёна и рекомендует статью к прочтению.

🔗 Читать: Вам кажется, что с вашей документацией что-то не так? Вам не кажется

#article #ru

Заметки о Release Notes

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

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

🔗 Читать: Writing better release notes

P.S

Мы уже не раз писали о релиз ноутах, дóроги они сердцу нашей редакции, так что предлагаю оглянуться назад:

1. The art of writing great release notes
2. Masters of Product Change: Taylor Singletary - Slack
3. Medium Release Notes: Historical record of the oft-overlooked communique known as the release note & Discord Changelogs

#changelog #en #article #resource

Вспомнилось тут в свете (надеюсь) скорого релиза IDE от JetBrains для техписателей, что есть кайфовый плагин для IntelliJ IDEA которым можно пользоваться уже сейчас.

Проверяет орфографию, грамматику и стиль, такой себе встроенный граммарли

🔗 Почитать больше о Grazie

#testthedocs #ide #en

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

🔗 Читать: Include diagrams in your Markdown files with Mermaid

#diagram #tool #en

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

Рекомендую, короткое спокойное чтиво на 5-6 минут, но сколько же души в этом всём. Может и вы откроете в себе любовь к “ископаемым”.

🔗 Читать: Why I collect and read old computer manuals

#visual #vintage #example #en

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

Мне время от времени поступают различные предложения от контор, которые готовы поддерживать и принимать Украинцев или помогать с релокейтом, буду ими с вами делиться по мере поступления. 🇺🇦 💪

Во-первых, для всего этого есть отдельный сервис: UA Talents

Во-вторых: Вакансия —> Компания: Klarna. Локация: Берлин, Германия. Предлагают релокейшн-саппорт.

В-третьих: Вакансия —> Компания: Star. Локация: Wroclaw, Poland; Remote, EU Time Zone, Клиент из UK

UPD:

ДОБІРКА САЙТІВ З ПОШУКУ РОБОТИ:

✅ https://helpukrainians.jooble.org
✅ https://www.jobaidukraine.com
✅ https://hireforukraine.org
✅ https://www.jobs4ukraine.eu
✅ https://remoteukraine.org
✅ https://hrforukraine.notion.site

Подолаємо труднощі разом та переможемо 🇺🇦

#career #vacancy

Доброго вечора, IT-спільнота, ми з України! Ситуація наступна: світу зараз як ніколи потрібні ви — вільні, працездатні, у безпеці.

До війни ми почали об'єднувати найдивовижніших, інноваційних людей України з метою створення неймовірних інноваційних продуктів. Тепер ми виходимо на новий рівень.
Ми хочемо надати вам роботу, офіс та житло. Ми хочемо знайти якнайбільше людей, які вірять, що майбутнє в їхніх руках.

Давайте зробимо світ кращим! 👇

https://bit.ly/3qlBc8I

#career #vacancy

Всем здрасьте! 🇺🇦

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

🗣 Ну а теперь к новостям:

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

Я мощнейше запотел, но все же оформил какую-никакую навигацию по каналу, протегал по темам и языкам все вышедшие посты. В будущем буду обновлять пост с навигацией (предлагайте дополнительные хэштеги в комментариях!) . Он будет следующим после этого и всегда жить в шапке канала.

2. Кроме навигации, улучшайзингу подверглась и айдентика 🧑‍🎨 Теперь посты будут сопровождаться красивой meaningful карточкой с кратким синопсисом поста, пример - в этом же посте.

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

👅 Языки:

#ru | #en

👷 Карьера:

#career — советы и всемозможные статьи о карьере техписателя
#conference — техписательские конференции, их записи и заметки
#resources — ресурс для саморазвития
#article — полезная статья, которая учит чему-то клёвому, что позволит стать более лучшим писателем
#vacancy — интересная вакансия или что-то связанное с наймом
#video — видео, видос, видосичек, видосюлька. И подкасты!
#book — книга/хендбук
#courses — курсы, программы для технических писателей

🛠 Технологии:

#tool — полезная утилита/приложение
#changelog — все о чейнджлогах, примеры, правила
#markdown — все о языке разметки Markdown
#reStructuredText — все о языке разметки reStructuredText
#asciidoc — все о языке разметки asciidoc
#LaTeX — все систему набора и вёрстки и язык разметки LaTeX
#ide — среды разработки и все что с ними связано
#vscode — все о Visual Studio Code, настройка, плагины, хитрости
#SSG — JAMStack, генераторы статических сайтов, Hugo, Jekyll, Antora, etc.
#testthedocs — тестирование документации, линтинг
#API — про документирование API, примеры, лайфхаки, подсказки
#diagram — про диаграммы (много про diagrams as a code), mermaid, UML
#screenshot — все про скриншоты, утилиты, сервисы и красивенькие фотоснимки экрана
#ai — про GPT, GitHub Copilot и прочее, где ИИ помогает нам писать

🧺 Общее:

#tonevoice — о правилах общения в документации
#language — что-то конкретно о языке, в основном английский
#legal — юридическая документация, лицензии
#styleguide — все о стилях и правилах
#DocsAsCode — все про подход к документации как к коду
#example — примеры документации (хорошие и плохие)
#uiux — интерфейсы, текст в интерфейсах, пользовательский опыт
#knowledgemanagement — менеджмент знаний, хранилища, тулзы, техники, советы и наблюдения
#versioning — про версионирование
#accessibility — все об аксессебилити в документации
#checklist — чеклист/шпаргалка
#vintage — винтажная документация, старые компьютеры, софт, техника, игры
#visual — про визуальную составляющую документации
#metrics — все о метриках документации
#random — что-то совсем косвенно относящееся к техписательству, юморески

Предлагайте новые хэштеги в комментариях!

Stripe заопенсорсили Markdoc. Markdoc — это authoring система на основе Markdown, на которой работает веб-сайт документации Stripe который мы все любим и ставим в пример каждый раз когда кто-то спрашивает примеры хорошей документации.

Markdoc подходит как для обычных статических сайтиков, так и для фичастых сайтов с документацией или личных блогов.

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

#tool #en #markdown #SSG

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

Следующая секция стайлгайда “Writing inclusive content” учит как не ненароком не обидеть своего читателя. Она довольно базовая, поэтому предлагаю взглянуть на отдельную статью про настройку своего линтера, которая помогает как раз находить такие узкие места в вашей документации.

Читать:
[1] New Relic Style Guide + 5 questions
[2] Reducing negative and biased language in documentation

#testthedocs #styleguide #voicetone #en #tool #language

shot-scraper — CLI тулза для для автоматического создания скриншотов веб-сайтов.

shot-scraper помогает автоматизировать создание свежих скринов веб-приложений (можно скринить конкретную часть приложения/сайта) для последующей интеграции в документацию, чтобы визуал не отставал от контента. Можно засунуть в CI\CD и всякое такое.

Бонусом у утилиты отличная документация и два [1]блог [2]поста которые рассказывют как всем этим пользоваться, и зачем, и как это создавалось.

#en #tool #visual #screenshot

Technical Writing 101

После 4 лет работы, 75 альфа-версий и 22 бета-версий следующfя мажорная версия Docusaurus готова к продакшену.

Из главных новшеств:
- Поддержка MDX: позволяет интегрировать интерактивные React компоненты прямо в документации. Пример
- Плагины: Docusaurus теперь имеет модульную архитектуру с системой плагинов. Основные функции, такие как документация, блог, страницы и поиск, работают как отдельные плагины. Доступны дополнительные плагины, например docusaurus-search-local, как замена Algolia. Больше плагинов тут
- Поддержка PWA
- Удобное версионирование документации

С более мелкими улучшениями можно ознакомиться в официальном блог посте

Читать: Announcing Docusaurus 2.0

#en #SSG #tool #markdown

Technical Writing 101

https://ifuckinghatejira.com/

#en #random

JetBrains в очередной раз очень сытно тизернули фичи грядущей IDE для технических писателей Writerside.

В этот раз — в самое сердечко, показали как работает встроенное тестирование документации: валидность разметки, целостность оглавления, ссылки и референсы, отпавшие картинки.

Не так давно я усиленно начал работать с AsciiDoc и решил, в виду более фичастого плагина, попробовать вернуться на WebStorm. И имею сказать, что забираю все претензии, которые имел к нему. За последние 4 или 5 лет, сколько я им не пользовался, вебшторм и все причастное к написанию в нем документации выросло до небывалых высот. Перешел с vscode и markdown на asciidoc+antora и webstorm, и не знаю бед.

В будущем канал сменит вектор с около-markdown штуковин и тулз на, как мне кажется, более зрелый и взрослый asciidoc, это моя новая любимая игрушка.

#markdown #asciidoc #tool #en #testthedocs

Сейчас проходит (подходит к концу) Write The Docs Prague, конференция для технических писателей с кучей интересных докладов.

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

Доклады на которые я хочу обратить внимание:

1. Beyond spell checking - what else can we check automatically?
2. Maintaining Documentation: Make It Easy!
3. How I convinced my boss to build our docs team

Если вам не терпится ознакомиться с заметками и вообще пронаблюдать как проходит конференция - WTD Twitter

В Slack добавляется функционал редактирования/создания документов. Компания, принадлежащая Salesforce, объявила сегодня на своей конференции разработчиков, что она создает новую функцию под названием Canvas, которая позволит пользователям создавать и редактировать полноценные документы прямо из интерфейса Slack.

Как это выглядит и работает можно глянуть в статья на The Verge или официальном блоге компании

🔗 Читать: Your digital HQ just got better with Slack canvas

#en #tool

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

Comics as Documentation частый гость на нашем канале, сегодня у нас и художница и программист Tomomi Imura c котиками и git-коммандами

P.S Ну и пока мы на визуальной теме, предлагаю вам ознакомиться с серией скетч-заметой с недавней конференции Write the Docs Prague. Можете полистать эти заметки и так решить какой из докладов вам интереснее послушать/посмотреть (<-- тут ссылка на ютубный плейлист Пражской конфы) полностью:

1. Creating documentation for the African audience.
2. Toward the broader globalization of Open Source: documenting your localisation Journey
3. Improve Customer Adoption with UI Help
4. The Art of Asking Questions
5. Cultivating a Stakeholder Network for Our Docs: How Building Relationships Improves Our Content
6. Beyond spell checking - what else can we check automatically?
7. Documentation as Marketing? From Conflict to Collaboration
8. Maintaining Documentation: Make It Easy!
9. How I convinced my boss to build our docs team
10. ADHD and its impact on the Creative Process for Writers
11. Two years of Markdoc: what we’ve learned about balancing developer and author experience

🔗 Читать: GIT PURR! Git Commands Explained with Cats!

#en #visual #example