Люди никогда не перестанут жаловаться на неуществующую спеку и недостаточную широту возможностей 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

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

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

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