Статья Федеральной торговой комиссии (ребята, что в США защищают правами потребителей и занимаются антимонопольной деятельностью) — "Как Технические Писатели могут способствовать безопасности программного обеспечения"

https://www.ftc.gov/about-ftc/bureaus-offices/bureau-consumer-protection/office-technology-research-investigation/guiding-to-safety-how-technical-documentation-writers-can-encourage-software-security

#career #en #article

А почитайте (не сейчас, конечно, вечер пятницы, алло. В Pocket там закиньте.) как-нибудь про наречия, хороший пост на Quora:

https://www.quora.com/Why-are-adverbs-considered-evil-I-keep-hearing-eliminate-adverbs-as-a-piece-of-writing-advice

#language #en #resource

В Google Docs наконец-то изобрели diff! <— это ссылка

#tool

Не могу не поделиться с вами очень хорошей новостью, в бету вышла Windows Subsystem for Linux 2.

К техрайтингу слабо относится, но я, напрмиер, гоняю там pandoc без всяких извращений.

https://devblogs.microsoft.com/commandline/wsl-2-is-now-available-in-windows-insiders/

P.S

Еще Microsoft активно педалит НОРМАЛЬНЫЙ терминал для всего этого дела вот тут (где брать готовые сборки я забыл, если вдруг соберете или найдете свеженькое - делитесь)

#tool

В Apple выкатили новую документацию и она великолепна!
"Параллаксный" скроллинг, всё аккуратно, аскетично и очень информативно, а главное — вконце есть раздел "Check Your Understanding" с вопросами по самой доке, берите на заметку:

https://developer.apple.com/tutorials/swiftui/creating-and-combining-views

Если вам лениво клепать аккуратные описания проекта, проставлять ссылочки и вот это вот всё, то вот вам генератор красивых README.md. Задаёт вопросы и за 10 секунд выплёвывает свёрстанный файлик 💫

У бота отклеилась ссылочка

#tool

Очень люблю Markdown и тут вот прилетел интересный вариант его применения в качестве замены Speech Synthesis Markup Language (SSML), на основе которого строятся ответы ботов типа Alexы и Google Assistant. https://voicebot.ai/2019/06/20/speech-markdown-is-the-simpler-way-to-format-text-to-speech-content-over-ssml/

#markdown

Почитайте интересный тред Продакт Менеджера docs.microsoft.com (одного из самых массивных сайтов документации, к слову)

https://twitter.com/DennisCode/status/1144108469617774592

TL;DR

Takeaways из треда:

1. Documentation is not easy.
2. Automation is key at scale.
3. Documentation is a partnership.
4. Users are part of the success equation.
5. Quantitative data without qualitative insights is not going to help you make good decisions.
6. Shared understanding can be achieved when things are written down.
7. Being attached to ideas is useless.
8. Avoid the "too many cooks" problem.
9. You will be wrong more than you will be right

#resource #article #en #career

Хороший, годный цикл постов про дружбу Markdown + ConTeXt (типографский брат LaTeX) и Pandoc

Зачем?

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

1. https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdown-part-1/
2. https://dave.autonoma.ca/blog/2019/05/29/typesetting-markdown-part-2/
3. https://dave.autonoma.ca/blog/2019/06/16/typesetting-markdown-part-3/
4. https://dave.autonoma.ca/blog/2019/06/23/typesetting-markdown-part-4/

#visual #uiux #en #markdown

Недавно пришлось иметь дела с ZenDesk и писать в нём буквы (а точнее переносить всё из Markdown в туда) и не могу сказать, что это был приятный экспириенс. Но нашлась вот такая тулза, которой можно скормить логин инфу и API токенчик и пушить это всё прям вот как вы себе и представляете.
Делюсь — https://github.com/mbuttler/docs-tools

Будем попробовать, а пока открыл комменты к посту и если у кого-то вдруг есть варианты получше (чтобы без sigh Ruby всё было, например) — дайте знать!

P.S Любители Руби, не обижайтесь!

Просто влюбился в Purple Numbers. Это же намного круче и удобнявее простых якорей на заголовки. Тут отличный пример и немного про сами Purple Numbers.

#uiux #tool #en

Пишите инструкции для здоровых людей

Рассказывает Максим Шишов.

Большинство инструкций — это ад. Они не учат пользоваться устройством, а рассказывают, как оно может навредить пользователю. Конечно, это защита от юристов и любителей сушить котов в микроволновке. Но из-за этого нормальные люди не читают инструкции, а потом приходят скандалить в сервис.

Хорошая инструкция наглядно объясняет, как запустить устройство, настроить и заставить работать. Значит, нужно описать все функции, как они могут быть полезны, как их настроить и отключить.

Если нужно соблюдать предосторожности при работе с техникой, перечислите сначала те, которые соблюдать точно нужно. Потому что если пользователь забьет на один пункт списка, это бросит тень на все остальные — и в итоге он все равно придет в сервис.

Понятные инструкции кормят половину Ютуба. Видео «Как вставить симку в Айфон» набрало миллион просмотров. Производитель может отнять хлеб у любителей и выпускать такие видео сам. Напишите инструкцию здорового человека — вы сэкономите на сервисном обслуживании, технической поддержке и получите постоянных клиентов.

Гугол напрягся и таки выкатил новость о Docsy.

Docsy — набор специально заточенных под документацию тем для Hugo. Предлагают всё это дело под слоганом "ваш проект перерос README на гитхабе? Тогда вам к нам!"

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

Такое нам надо!

#SSG

В канале @TW_Ukraine поделились ссылкой (если ваши руки в компании дотягиваются до резюме сотрудников. Мои — да. Если у вас возникают вопросы "почему?", то вы работаете или в продуктовой компании или чего-то не улавливаете в устройстве бизнеса) на бест практисы по написанию резюме. Советы дают бывший Тех Лид гугла и чувак, успевший поработать в LinkedIn и Microsoft. Короче, можно верить.

#book #resource

Запустился ImportDoc, — сервис, позволяющий грамотно эмбедить контент из Google Docs прямо в вебстраничку. Никаких iframe'ов, ImportDoc наследует стиль странички, в которую это всё дело встраивается. Тут видео-демонстрация, а вот тут официальный сайт, ну и для посмотреть на деле как это все работает — CodeSandbox пример

#tool

Редакция блога ушла в недельный отпуск, не переключайтесь.