Фил Девис из Tech Whirl написал небольшую рефлексивную ретроспективу об истории Техрайтинга. В ней он размышляет об истории техписательства и о том, как новые подходы можно спроецировать на старые решения и какие профиты мы с этого получим.

https://techwhirl.com/we-are-living-in-a-golden-age-of-documentation/

#article #resource #en

Алсо, тут yet another переизобретатель велосипеда. 0 days since кто-то пытается изобрести ИДЕАЛЬНЫЙ язык разметки документации.

https://www.freecodecamp.org/news/we-need-a-new-document-markup-language-c22e0ec44e15/

#markdown #asciidoc #en

Kubeflow активно опенсорсит свои процессы, в этой статье (https://medium.com/kubeflow/the-making-of-kubeflow-1-0-designing-for-stability-and-broad-market-adoption-a190358e96b6) можно найти ссылки и посмотреть как у больших дядь устроены Док-спринты и вообще поглазеть на их борды и порыться в процессах и полисях. Ну это так, для общего развития.

#uiux #en #resource #article

Ловите гист со сворачивающимися блоками в Маркдауне. Там в комментах еще всякие вариации, можно под этот дропдаун много чего прятать.

#markdown #en

День релизов! (с опозданием)

Доношу до вашего сведения, что недавно хорошенько так обновился code-server.
code-server -- самая правильная версия VSCode, ибо под каким бы соусом не мариновали Electron приложения, оно им и останется. Тут всё иначе, вы запускаете локальный (или любой другой!) сервер и заходите на 127.0.0.1:8080 и вуа-ля, у вас больше не запущено два (ато и три, если вдруг вы зачем-то пользуетесь НЕ веб-версией слака или каким-нибудь Дискордом) инстанса хрома.

Для сравнения мемори футпринты:

```VSCode - 6 электрон-процессов ~ 1Gb of RAM usage

325.16 Mb /usr/lib/electron6/electron
316.66 Mb /usr/lib/electron6/electron
213.11 Mb /usr/lib/electron6/electron
152.18 Mb /usr/lib/electron6/electron
85.18 Mb /usr/lib/electron6/electron
17.36 Mb /usr/lib/electron6/electron
-----
1109.65 Mb

code-server - 3 code-server процесса кушают ~375Mb + 1 вкладка Хрома ~100Mb in host

148.06 Mb /usr/bin/code-server
125.86 Mb /usr/bin/code-server
101.29 Mb /usr/bin/code-server
-----
375.21 Mb

```Результат, как грица, на лицо. Замеры проводились на более старой версии, сейчас может дела даже лучше.

Кроме того, зарелизился Vale v2.1.0, в нем тоже пара новинок. Добавлена поддержка многословных исключений и raw скоупы, чтобы можно было линтить необработанную размету, такой себе улучшенный --ignore-syntax.

А объединяет эти две новости то, что весь редакторский состав этого блога последний месяц в поте лица боролся за то, чтобы две эти шикарные вещи (code-server + vale) наконец-то нормально заработали вместе.

Для полноценной работы вам нужно просто поставить самые свежие версии code-server, vale и vscode-vale.

Пользуйтесь, не болейте. ❣️

#ide #vscode #en

На Гитхабе завели awesome-техрайтинг список, инфы пока мало, но парочка интересных ссылочек уже есть, можно поскроллить на досуге :3

По соседству живет еще awesome-jamstack, тоже не топовейший список, но можно выцедить полезностей.

#resource #book #en #SSG

Закончился Season of Docs 2019, о финалистах можно почитать тут. А тут можно ознакомиться со всеми 44 успешно завершенными проектами. Отдельно хочу подметить, что по обеим ссылкам доступны отчеты о проделанной работе, крайне занимательно и познавательно!

#example #conference #en #resource

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

Имеем: Sony PlayStation Network, мое желание купить игру, очень агрессивная и недокументированная анти-fraud система, очевидное отсутствие техписателя.

1. Жму, значится, я кнопку "Купить и оплатить игру", получаю ошибку "при обработке заказа произошла ошибка. Попробуйте повторить позже" (капитализация и пунктуация сохранены);
2. Меняю карту оплаты на ту, на которой есть деньги;
3. По совету сообщения об ошибке пробую еще раз;
4. Получаю аналогичную ошибу;
5. Звоню в техподдержку, где мне говорят, что уже после первой попытки из пункта 1 я получил бан транзакций на 24 часа (по другим сведениям неделя и больше).

Зачем было советовать попробовать еще раз, если за это я получу бан (возможно продлённый, возможно повторный)? Почему было не уведомить о существующей, как я понял, годами системе? Почему не сказать о бане на nn недель/nn часов или хотя бы вообще о бане? Почему не добавить код ошибки к этому сообщению, когда во всей остальной системе PlayStation любая ошибка содержит в себе соответствующий код, который легчайше гуглится?

Из этого получается:

1. Очень (очень) недовольный клиент;
2. ОЧЕНЬ загруженную техподдержку, которой приходится тратить время на выслушивание моей боли, на поиск моего аккаунта, на информирование меня о моем бане;
3. Испорченный имидж компании, которая буквально из имеющейся налички может строить дома, но не в силах нанять техписателя (и, судя по постоянно отваливающейся логин форме на официальном сайте, и программиста);
4. Потерянные приколы за предзаказ игры, который заканчивается через 4 дня;
5. Потерянные 20% кэшбека в честь карантина, который заканчивается еще через несколько дней.

Так ли должны работать многомиллиардные компании с крупнейшей юзербазой игроков в мире? Не уверен.

#uiux #example #en

Пока вокруг бушует хаос, техрайтеры не перестают писать.

Очередная саексесс-JAMStack-стори, в этот раз от техписа из LINE. Чуваки перекатились с Middleman на VuePress и рассказывают о том как это было:

https://engineering.linecorp.com/en/blog/line-developers-site-from-middleman-to-vuepress/

Гийом Гомез, разработчик Rust и активный контрибьютор Servo (тот самый революционный движок для Firefox) написал заметку с советами о том, как документировать Rust-проект:

https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate

#SSG #article #en

Такой вот день подкастов!

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

1. Подкаст с участием UX-писателя из Netflix. Прежде чем попасть в Нетфликс, Бен Барон успел поработать в Фейсбуке и Воцапе. В подкасте обсуждаются такие темы как:
- Каково работать в Netflix;
- Как преуспеть в UX-пистаельском деле;
- Какие проблемы возникают при проектировании, когда речь заходит об использовании слов в таком приложении, как Netflix?

https://www.writersofsiliconvalley.com/blog/2020/3/3/ux-writing-netflix-ben-barone-nugent

2. The Manuscript Podcast

Этот подкаст про писательство и разработку технологических продуктов. Каждые пару недель приходит какой-то известный технический писатель, Instructional дизайнер, UX-писатель или контент-стратег.

Читал много хороших отзывов, должно быть нескучно

https://brenobarreto.co/the-manuscript-podcast/

#video #resource #article

У Microsoft очень сильный Документационный отдел, у них куча прикольных самописных плагинов для ➡️VS Code ⬅️ (тут ссылка на пак со всеми сразу.)

Так вот, к чему это я.

🎁 Сегодня M$ запустили мини-конкурс с подарочками за контрибьют в их документацию. Всего-то нужно иметь аккаунт на гитхабе и зорий техрайтинговый глаз и зареплаить на этот твит ссылкой на PR.

Контрибьютить можно в такие доки:

- 📃 Build Desktop apps - UWP, Win32, WPF, Windows Forms

- 📃Windows UI Library - Controls for UWP apps, Controls API reference

- 📃Build with Windows - Windows Subsystem for Linux (моё любимое), Python, NodeJS, Mac to Windows guide

-📃Windows Hardware Developer - Tools and Drivers

Если вы начинающий техпис, это будет отличной строчкой в вашем портфолио, дерзайте

#vscode #vacancy #en #resource

Тут вот небольшое продолжение про WeasyPrint, про который я писал раннее. Уже и темплейтик сделали, выглядит неплохо.

#en #tool

Люди никогда не перестанут жаловаться на неуществующую спеку и недостаточную широту возможностей Markdown. Сегодня до нашего эфира донёсся новый крик на этот счёт. Тут товарищ буквально умоляет перестать писать доки на Markdown и предлагает свалить куда угодно, но подальше от всеми любимых .md файликов.

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

#markdown #article #en

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

Сегодня у нас в гостях gifcap. gifcap - полностью client-side записывалка экранов, которая сразу же делает гифку из записи. Ничего никуда ни на какие сервера не уходит, всё у вас, прямо на месте. Ну и конечно же полный опенсорц.

#visual #tool

Карантин карантином, а хорошие новости по расписанию.

Microsoft рализит свою версию Grammarly под названием Microsoft Editor. Судя по последним маркетинговым роликам, где-то в недрах MS завелся офигенный моушн дизайнер, ролик с рекламой этого Editor'a ну очень красивый.

Обещают интеграцию со всем и вся: Word, Outlook, Браузер.

В перечне фишечек такое:

- Provides suggestions to improve sentence clarity
- Suggests alternate vocabulary
- Reminds you when to use formal language
- Supports over 20 languages
- A similarity checker helps catch plagiarism or lets you quickly provide citations if you’re the one writing
- Suggest alternative punctuation
- Suggest gender-neutral and inclusive terms to reduce inherent bias in writing
- Provide information on how long it takes to read or speak your document

#testthedocs #tool #en

Компания documentat.io — команда экспертов по технической документации. Они пишут руководства пользователя, документируют API, составляют хорошие ТЗ и наводят порядок во внутренних базах знаний.

У ребят сейчас открыт аттракцион невиданной щедрости: они предлагают всем желающим бесплатный аудит документации.

Покажите им ваши user manuals, документацию на API, README к вашим опенсорсным проектам, внутреннюю документацию для разработчиков, и они расскажут вам:

- Как сделать вашу документацию более понятной и полезной.
- Как переехать с неудобного инструментария (MS Word? Старые wiki?) на удобный.
- Как надо правильно готовить Confluence, чтобы его читали и не захламляли.
- Как навести порядок в массиве документации.
- Как выстроить процессы работы с документацией в условиях всеобщей удаленки.

Разумеется, перед работой будут подписаны все необходимые NDA.

Еще раз: этот аудит бесплатен!

Пишите на audit@documentat.io.

http://documentat.io/#audit

#vacancy #resource #article #en

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

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

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

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

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

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

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

#article #en

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

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

#tool #SSG #en

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

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

>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

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

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

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

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

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

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

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

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

#en #example #resource