Technical Writing 101 🇺🇦

2022-02-28 01:38:19 Channel name was changed to «Technical Writing 101 » Открыть/Комментировать

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

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

Читать: Why I collect and read old computer manuals Открыть/Комментировать

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

Читать: Include diagrams in your Markdown files with Mermaid Открыть/Комментировать

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

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

Почитать больше о Grazie Открыть/Комментировать

2022-02-07 16:12:24 Заметки о 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 Открыть/Комментировать

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

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


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

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

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

2022-01-21 15:01:53 Docs for Developers

Обзор на книгу Docs for Developers: An Engineer’s Field Guide to Technical Writing, которая вышла в сентябре 2021. В посте есть спойлеры, если хотите сохранить интригу не читайте этот пост.

Книга написана в соавторстве техническими писателями из Google, Microsoft, Stripe и Monzo.
Авторы говорят, что:

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

Еще обсуждение книги с авторами можно послушать в подкасте Write the Docs.

Что зашло

- Легко и быстро читается.

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

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

- Есть список необходимых инструментов, чтобы написать и опубликовать первую документацию (Hugo, Vale, Netlify).

Не зашло

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

- Я ожидала прочитать реальные истории из опыта авторов, про подходы к документации в их компаниях и много практики. Этого в книге нет.

Однако

Книга мне понравилась. Но перечитывать и держать ее под рукой я не буду.

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

Если вы технический писатель с опытом, то бросать все и начинать читать книгу не надо.

Я не верю, что много разработчиков или менеджеров прочитает ее, особенно кто-то из стартапа, ведь это 200 страниц.

#developerexperience Открыть/Комментировать

2022-01-18 16:19:48 Обновилось годное дополнение для Google Docs: Docs to Markdown.

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

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

2022-01-04 13:24:54 Курс по документированию API от Тома Джонсона теперь доступен в удобных форматах!

1. PDF
2. EPUB
3. MOBI

Открыть/Комментировать

2021-12-22 16:31:32 Интересный взгляд на Season of Docs 2021 изнутри.

Redocly (генератор Swagger-API-доки) рассказали как прошло их участие в Google Season of Docs.

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

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

Можно поглазеть на созданные PRы, ознакомиться с таймлайном, чтобы примерно понять сколько что займет времени и наконец-то задуматься об участии в следующем году!

Читать: Redocly - Season of Docs 2021: Case study Открыть/Комментировать