Technical Writing 101 🇺🇦

Очень люблю 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

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

#tool

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

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

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

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

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

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

P.S

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

#tool

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

#tool

А почитайте (не сейчас, конечно, вечер пятницы, алло. В 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

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

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

Обновился до 4-й версии Markdown-редактор Inkdrop. Честно говоря, я уже совсем перестал обращать внимание на "специализированные" Markdown-редакторы, т.к ничем они друг от друга не отличаются и ужасно ограничены в наборе фукций. Но Inkdrop это исключение, ведь там есть плагины и даже полезные! До VSCode еще как до луны, но потенциал имеется, пробуйте.

#ide #en #markdown

Давненько в закладках лежит хороший разбор плюшек, которые предоставляют Docz, Storybook и Styleguidist для интерактивной документации UI-компонентов (и API'шек)

Кроме того, в статье хорошим и понятным языком рассказывают, что такое MDX

https://css-tricks.com/front-end-documentation-style-guides-and-the-rise-of-mdx/

#uiux #tool #en

На горизонте никаких интересных статеек, да и уже пятница, чо напрягаться.

Пусть и с запозданием, но вот хорошее пятничное чтиво от Increment про open-source, коммьюнити и иже с ними.

https://increment.com/open-source/

Вообще Increment отличное издание, советую подписаться и почитывать чем живут современные команды (RSS для понимающих)

#resource #article #en

⚡️⚡️⚡️

Свершилось! Один из самых гибких линтеров (Vale) вот-вот станет работать с sandboxed приложениями (читай Google Docs, Microsoft Word, Chrome)

https://medium.com/@jdkato/vale-comes-to-the-desktop-b813b24b66ba

#tool #testthedocs #en

Что бы вы выбрали?
anonymous poll

Go to File, and then select Save. – 49
👍👍👍👍👍👍👍 67%

Select Save from the File menu. – 24
👍👍👍 33%

👥 73 people voted so far.

Анимированные презентации терминала. Можно экспортировать в SVG, GIF, или HTML+CSS

https://neatsoftware.github.io/term-sheets/

Вдруг пригодится.

#tool #visual #screenshot

Наткнулся тут на бложик техрайтера из Google, он пишет документацию для Chrome DevTools.

Очень понравилась оттуда статья про то, что может и не все бест практисы одинаково полезны (а может и полезны!) и применимы и размышления на счёт того, что со всей этой информацией нам делать и как измерять полезность конкретно взятой доки (солюшен очень прост и я с ним согласен)

https://kayce.basqu.es/blog/best-practices

Остальное тоже почитайте!

#resource #en #article

Для быстрых (как публичных, так и приватных) заметок поверх любой веб-странички (а также PDF и EPUB) пытаюсь пользоваться https://web.hypothes.is

Если вы плотно работаете над текстовкой какого-либо сайта/книги то вот это то, что нужно

#tool #en

Немножко про организацию документации.

https://medium.com/@brooke.wayne/how-to-organize-your-docs-bd797c616b48

Статья описывает базовые вещи, но интересный тейкэвэй оттуда это термин Undernets:

>Undernets are the “non-formal and unintentionally walled off bits of knowledge that [folx] document in private”, also known as “rogue docs or sheets [others] create for themselves. These are often incorrect, out of date, or not shared with the entire team.”

#knowledgemanagement #resource #en

Второй день не пойму related ли эта тема тут или нет, но я люблю буковки поэтому ловите.

Детальный и супер задротский разбор пресловутой PDF-ки Mueller Report. Там обсуждают PDF стандарты и их нарушение, выясняют как была создана эта пдф-ка и что пошло не так, а также софт которым цензурят такие документы и всякое такое. Всё это дело рассказывает дядька, который >ISO Project co-Leader for ISO 32000 (the PDF specification) and Project Leader for ISO 14289 (PDF/UA)

https://www.pdfa.org/a-technical-and-cultural-assessment-of-the-mueller-report-pdf/

#article

На Season of Docs уже доступен список опенсорс проектов в которые можно контрибьютить документацию:

https://developers.google.com/season-of-docs/docs/participants/

#career #resource #en