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

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

Эрин Грин - мадама техписатель с 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

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

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

#markdown #diagram #tool

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

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

#vscode #tool #diagram

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

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

#resource #en

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

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

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

#video #article #en

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

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

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

#article #example #conference #en

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

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

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

#markdown #en #tool

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

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

Будьте как Stripe.

#example #en

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

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

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

#article #en

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

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

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

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

#cnahgelog #en #uiux

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

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

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

#vacancy #resource #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

Words To Live By:

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

#example #en

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

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

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

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

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

Сам-то я предпочел бы хранить все их 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

*вдох*
ReadMe Flavored Markdown
*выдох*

https://docs.readme.com/rdmd/docs

#tool #markdown

Небольшой текст с рассуждениями о том, когда лучше публиковаться (документацию), когда уже написано много, или когда написано мало, и что вообще такое "много", "достаточно", и "мало".

https://ddbeck.com/how-small-is-enough/

#resource #article #en

Такой интересный год для Microsoft-опенсорса выдался:

- Microsoft забирает назад свои слова про опенсорс: "Microsoft was on the wrong side of history when open source exploded at the beginning of the century",
- Улучшает поддержку Linux в WSL2, позволяя запускать Linux-GUI приложения прямо в винде,
- Чинит трансляцию GPU вызовов в ядро, добавляет GPU-ускорение и DirectX (!) в WSL2,
- Выпускает нормальный (опенсорсный!) терминал.

И наконец-то про документацию:

Анонсированный в 2019 Fluid Framework представляет из себя "конструктор лего" для документов, такой себе Google Docs, если хотите. Я больше это вижу подвижкой в сторону Notion-изирования, больше никакого создания и сохранения и пересылки документов. К 2020 практически все офисные пакеты ушли от парадигмы файлов и полностью окунулись в коллективное создание всего и вся в "облаке". Так вот, теперь это всё опенсорсное, весь Fluid Framework с недели на неделю появится на гитхабе и предположительно там всё на TypeScript, и судя по всему, это интересный фундамет for what's to come.

Почитать больше можно тут.

#article #en

А ещё у Notion персональный план стал бесплатным и без ограничений на блоки. Теперь у вас ровно 0 причин не попробовать эту приятную тулзу.