Не всё ж нам истории с хэппи-эндами читать.

Команда техписаталей Rust - всё.

Формально она существовала до сегодня, а на деле прожила с августа 2016 по август 2018.  

- Вся стандартная библиотека уже задокументирована, а новые API будут описывать разработчики.
- Книга по Rust активно мейнейнится двумя людьми
- Cargo (пакетный менеджер) документируется Cargo-тимой
- Ошибки которые стреляет компилятор описывает команда, занимающаяся (кхе) разработкой самого компилятора.

Больше деталей тут:

https://blog.rust-lang.org/inside-rust/2020/03/27/goodbye-docs-team.html

Всем чилловых выходных. (если у вас все дни еще не смазались в один длинный понедельник)

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

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

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

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

>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

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

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

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

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

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

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

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

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

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

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

Эрин Грин - мадама техписатель с 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", но если у вас есть деньга - просит поддержать. У всех файлов довольно говорящее название, но если всё еще не понятно что к чему, то вот тут можно понажимать на каждый документ отдельно и понять что к чему.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Будьте как Stripe.

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

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

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

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

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

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

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

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

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

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

История о том, как команда 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/

Words To Live By:

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

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

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

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

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