Technical Writing 101 🇺🇦

📊 State of Docs 2025 is here!

The State of Docs 2025 report just dropped — super interesting stuff on how to track success in docs, use AI, and think about the future of docs.

"This State of Docs Report 2025 brings together insights from tech writers, product managers, engineers, and leaders across the industry. We‘ll dig into how companies structure their doc teams, how they measure success, how docs fit into the product journey, and how new tech like AI is changing how we think about and create documentation."

#en #article #conference

🚀 Exciting update for technical writers and developers using Google Docs!

📝 Now, you can import and export Markdown directly in Google Docs. To enable this feature, simply go to Tools > Preferences > Enable Markdown. This means seamless collaboration on software documentation in Docs, which you can then export in Markdown format for other supporting tools.

🔗 Read more: Import and export Markdown in Google Docs

environmental documentation

Есть чувство, шо GitHub вот-вот перевернет рэп игру своей новой функцией Blocks.

Blocks ー переосмысление того, как мы смотрим на репозитории. Blocks предлагают сделать репозитории с кодом интерактивными, что-то на подобие Colab Notebooks.

Среди уже показанных фишек:

➡️ Встраивание интерактивных-демо-блоков с кусками рабочего приложения вместо скриншотов;
➡️ Создание справочной документации с возможностью поиска по ней (встроенный SwaggerUI anyone?);
➡️ Визуализация и возможность сортировать, ворочать туда-сюда CSV и JSON как эксельку в гуглодоках;
➡️ Редактирование и встраивание диаграм опять же, интерактивным блоком прямо в документации.

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

Бонус треком GitHub представил проект TestPilot ー искуственный интеллект, который пишет за вас юнит тесты, основываясь на документации и уже существующем коде. Еще +1 повод содержать свою документацию в порядке.

🔗 Срочно читать: GitHub Blocks Technical Preview: Reimagine repositories

Допомоги/Підтримки пост

Гайз, хочемо поділитись з вами штучним інтелектом який може створити унікальне зображення чого завгодно, в будь-якому стилі, треба просто описати це за допомогою тексту 📝
Чим докладніше опис - тим краще😉

P.S. частина коштів йде на допомогу бійцям полку 3 штурмової бригади.💙💛

P.P.S Картинка згенерована по запиту "A person writing a post for technical writing blog", seems close enough

В дев-комьюнити ReadME, который хостит GitHub, вышел годный пост про ведение рабочих заметок.

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

Применяя такой подход к ведению заметок, команды легко алайнятся в совместной работе и находятся "on the same page" в плане понимания важной информации и идей.

🔗 Читать: Documenting knowledge: a guide to successful note-taking

У Ноушна намечается что-то очень интересное! Бойтесь, писатели, оно уже пишет всё за нас!

Минутная видео-презентация по ссылочке.

👀 Смотреть: Introducing Notion AI

Ну штош, будем попробовать.

Без поддержки Asciidoc не так интересно, как хотелось бы, но все еще хз даже чего ожидать

Зарелезилась популярная платформа для документации GitBook, теперь версия 3.0

Что нового?

- Частичный редизайн UI-ки публичных страничек.
- В хэдере появилась возможность делать меню с дропдаунами.
- Поиск переехал в правый верхний угол.
- Края элементов, по веянию моды, скруглились почти везде
- Новенькие шрифты
- Новый элемент для лендингов: block: cards
- Интеграции!

Интеграции:

- Arcade
- Fathom
- Figma
- Google Analytics
- Intercom
- Jira
- Linear
- Mailchimp
- Mermaid
- Plausible
- RunKit
- Sentry

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

🔗 Читать: GitBook 3.0: Document everything, from start to ship

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

🔗 Читать: Ask HN: Any great books about technical writing?

#book #resource #career #en

Интересно наблюдать за разным ходом мысли в решении схожих проблем.
👁___👁

Разработчики Han Wang и Hahnbee Lee радикально подошли к поддержанию документации в актуальном состоянии. Теперь ссылку на документацияю можно натурально прибить гвоздями в IDE (VSCode) и получать уведомления в реальном времени, мол, обнови документацию после изменения кода.

Как это выглядит на практике - можно ознакомиться в этом видео.

В данный момент "прибитие гвоздями" поддерживается в следующих сервисах:
- Notion
- Google Docs
- Confluence
- GitHub
- Slack

🔗 Скачать: Mintlify Connector

#tool #en #vscode #ide

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

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

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

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

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

#en #tool

Сейчас проходит (подходит к концу) 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

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

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

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

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

#markdown #asciidoc #tool #en #testthedocs

Писать по предложению на каждой строчке оказалось довольной удобной техникой.

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

Статья сжато и понятно описывает все преимущества такой техники. Современные языки разметки (md,adoc) буквально нативно позволяют это делать не разрывая строку при последующей сборке html/pdf, и т.д). Попробуйте!


➡️Читать: Writing One Sentence Per Line

#en #article

Cегодня у нас в эфире тщательно подобранные материалы на почитать и профессионально развиться.

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

Если вы давно думали чего бы такого читнуть, чтобы стать лучше, как писатель - this is it.

Советую проклацать прямо по всем ссылочкам, узнал много нового даже из залинкованных вики-статей 👍

📖 Читать: Technical Writing: a bibliography, tips, and tricks

#book #en #resource #language #styleguide

https://ifuckinghatejira.com/

#en #random

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

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

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

Читать: Announcing Docusaurus 2.0

#en #SSG #tool #markdown

Technical Writing 101