Technical Writing 101 🇺🇦

Зашел я тут недавно в техрайтерские чатики и там снова про диаграммы.

Сам-то я предпочел бы хранить все их as a code, но есть и альтернативное мнение/решение.

На днях зарелизился абсолютно великолепный плагин для VS Code и наша редакция никак не могла пройти мимо.

Draw.io Integration! Исходники, естественно, открыты.

Фичи:

- Редактирование .drawio или .dio файлов как в редакторе Draw.io, так и голый XML (можно даже side by side).
- Редактирование .drawio.svg (svg!)
- По умолчанию используется офлайн версия Draw.io.
- Т.к Draw.io тоже опенсорсный продукт, он может быть и self-hosted, а это расширение поддерживает кастомный URL-адрес для вашего Draw.io инстанса .
- Темы

Когда VS Code'ный API для сторонних редакторов будет стабилен, автор обещает добавить поддержку редактирования .drawio.png

#diagram #DocsAsCode #en #vscode #tool

Проклятие знания

Совет Стивена Пинкера (из Гарварда, если вам вдруг важно).

Если ты что-то знаешь, то автоматически думаешь, что другие тоже в курсе. Но это не так — и это мешает вам писать нормально. У тебя в голове есть контекст, знания, опыт — а у читателя всего этого нет, поэтому иногда вы говорите на разных языках. Если вас хоть раз просили объяснить «будто мне 5 лет» — то это из-за «проклятия знания».

Как с этим бороться: дайте прочитать текст кому-то ещё. Например, редактору. Или маме. Другой человек легко найдёт все моменты, которые не понимает, а вы сможете их переписать.

Words To Live By:

https://twitter.com/santiwilly/status/1257779891711475716

#example #en

История о том, как команда Azure Sphere Security Services в качестве эксперимента перекатывалась с *перекрестился* SharePoint и Microsoft Word на Markdown и Git, и что из этого вышло

TL;DR

Кто бы мог подумать, что пересесть с квадратных колёс на круглые (no pun intended) всем понравится, и как следствие: "AS3 team considers the experiment incredibly successful"

https://caitiem.com/2020/03/29/design-docs-markdown-and-git/

#DocsAsCode #markdown #articke

Гитлаб предлагает пополнить свое (ну, то есть ваше) портфолио опенсорс контрибьюшнами в документацию и предоставляет список простеньких ишшью которые хорошо бы было пофиксить.

В довесок делятся перечнем "хороших первых контрибьюшнов" в качестве образца.

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

#vacancy #resource #en

Нужно написать релиз ноуты? Чейнджлоги? А вдохновения нет?

А может их никто и не читает вообще и можно написать туда абы что?

Ответы на эти и еще многие другие вопросы в прекрасной статье про искусство написания релиз ноутов:

https://uxdesign.cc/the-art-of-writing-great-release-notes-6607e22efae1

#cnahgelog #en #uiux

Экосистема vs Среда обитания.

В этой статье идет речь о том, что сравнение программных «экосистем» - странный способ выбрать инструмент для документации. Автор предлагает несколько иначе подходить к выбору инструментария.

https://ddbeck.com/static-site-ecosystems/

#article #en

Лучшая. Getting. Started. Дока. Эвэр.

https://stripe.com/docs/payments/integration-builder

Будьте как Stripe.

#example #en

Ни дня без велосипеда 🤷‍♂️

Некто Томас Аллмер, основатель Open Web Components выпустил MDJS, вариант Markdown, который позволяет разработчикам включать код JavaScript в документацию на Markdown. Вот тут еще статейка.

Я, скорее всего, чего-то просто не понял, но в моей вселенной уже существует MDX.

#markdown #en #tool

А почитайте о приключениях Open Geospatial (OSGeo) Foundation во время Гуглового Season of Docs. В статье затрагивается тема "Что на самом деле хорошая документация".

https://opensource.com/article/20/4/documentation

P.S Написано хоть и хорошо, но от статей с чертовой печатной машинкой в заглавной картинке уже на физическом уровне плохеет. Если вам в жизни представится шанс и полномочия из какой-то статьи такую машинку удалить - считайте жизнь прожита не зря.

#article #example #conference #en

Опять эти подкасты! Но на этот раз близкая мне тема (юморок)

Приглашенный гость - Алан Дукет из Propsify

В этом эпизоде вы узнаете:
👉 Люди на самом деле не хотят читать то, что вы пишете
👉 Почему Аллан перекатился из службы поддержки в техписы
👉 Нужно ли добавлять шутки в документацию! (?)

#video #article #en

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

https://twitter.com/e_mln_e/status/1248679254633537536

#resource #en

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

Ловите плагин для VS Code со всроенным Asciiflow.

#vscode #tool #diagram

Damn son, да это же майндмепы с синтаксисом markdown. Интерактивный редактор присутствует, срочно нужен плагин для VS Code.

На сегодня это последний пост, обещаю. Накопилось :(

#markdown #diagram #tool

Один из приятных побочных(?) эффектов пандемии — всеобщая сплочённость, не только в жизни, но и в интернете. Огромное количество курсов, уроков, тренингов и всякого такого стало либо бесплатным, либо предоставляется с огромной скидкой.

Для техрайтеров тоже отсыпали бонусов.

Эрин Грин - мадама техписатель с 10-летним опытом и автор блога с говорящим названием readthefriendlymanual.com делится своими наработками:

- "12 Principles of Agile Documentation” eBook
- System Functionality Outline Worksheet
- Docs Regression Checklist
- Docs Review Worksheet
- Documentation Reviews Slide Deck
- Scrum Ceremonies

Ну как делится, предлагает 100% скидку с промоодом "COVID19", но если у вас есть деньга - просит поддержать. У всех файлов довольно говорящее название, но если всё еще не понятно что к чему, то вот тут можно понажимать на каждый документ отдельно и понять что к чему.

Всё очень красиво задизайнено, свёрстано и вообще всевозможно полезно. Инджой!

#resource #en #book

Отвлекаясь от бешеного потока рабочих тасок, доношу до вас благую весть, был обнаружен (ЖЖ Артемия Лебедева) сайт The Writer который написан какими-то гениями.

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

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

Тут вам и стайлгайд, и readability-чекалка и шикарнейшие микро-рассказы о проделанной работе.

Советую провести на сайте 30-40 кровных минуток обеденного перерыва и поизучать тон написанного. Одна история о сотрудничестве с Vaseline (да-да, тот самый вазелин) чего стоит.

#en #example #resource

Курс про документацию, но фактически: про коммуникации между участниками проекта и передачу знаний

Семен Факторович из documentat.io повторяет свой онлайн-курс по технической документации, но сегодня в лекции, фактически, рассказывает о том, что документация - лишь один из каналов реализации процесса коммуникации между стейкхолдерами проекта и о том, когда нужно в этом канале передавать знания через документацию, а когда нет.

Включайте: https://www.youtube.com/watch?v=w0DNTDE3EgE

Названия *никсовых утилит это отличный пример того, что будет если не приставлять к разработчикам грамотного технического писателя и давать им называть всё так, как им кажется правильным. Обскурные названия с которыми практически нет никаких ассоциаций у рядового пользователя, это такая же проблема, как и плохая документация.

Об этом собственно открыто и пишут:

>Giving cryptic names to software is a well-established UNIX tradition, and the explanations are often missing from the documentation, either because the developers imagine it's obvious (usually wrongly) or because they think nobody cares (and here they're usually right, or it would turn up as FAQ material).

На Wiki проекта Debian есть очень обширная база-глоссарий с расшифровской всевозможных диковинных названий. У многих из них очень необычная история нейминга, чаще всего смешная. Да и вообще там всё очень дружеским таким языком написано.

Отдохните, выдохните, полистайте, и снова за работу

https://wiki.debian.org/WhyTheName

#en #resource #article

Сфинксополезностей пост.

sphinx-hoverxref - это расширение Sphinx, показывающее плавающее окно (всплывающие подсказки или модальные диалоги) в перекрестных ссылках документации, в которые встраивается содержание связанного с ними раздела. С sphinx-hoverxref вам не нужно нажимать на ссылку, чтобы увидеть, что там.

#tool #SSG #en