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

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

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

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

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

#en #example #resource

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

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

Эрин Грин - мадама техписатель с 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.noscript (noscript!)
- По умолчанию используется офлайн версия 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 причин не попробовать эту приятную тулзу.