Technical Writing 101 🇺🇦

Держите до слёзок актуальный привет из 1996. Это кусок внутренней рассылки из Университета Калифорнии. Оформил вам это красиво в заметочку, печатайте, вешайте перед собой и никогда-никогда не забывайте обо всём, что написано в этой памятке. Назовём это манифестом техрайтера.

#styleguide #en #article

↓↓↓↓↓↓↓↓

DocBook или DITA? Положение дел на 2020й год.

https://paligo.net/blog/single-sourcing/docbook-or-dita-for-technical-writing-what-is-the-difference-in-2020/

TL;DR: Люди с большим опытом в DITA приходят к выводу, что it wasn’t worth it. There was a better way, что и требовалось доказать, да.

#tool #en

Metadoc - это персонализированная док-платформа для разработчиков (и технических писателей). Документы могут быть сгенерированы из исходного кода (или любого источника метаданных, включая контент произвольной формы). Пользователи могут добавлять закладки и заметки, сохранять их в общих рабочих пространствах и делиться ими со своей командой. Более подробная инфа на оф. сайте https://beta.metadoc.io

#tool #en

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

Супер-современный и всячески прогрессивный UK-based банк Monzo выложил в открытый доступ просто охуительного, пардоньте, качества бренд-гайд по своему внутреннему Tone of Voice. 🗣

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

Рекомендуется к копированию, модификации и выборочному мотанию на ус их правил. Мне очень понравилось, надеюсь понравится и вам.

https://monzo.com/tone-of-voice/

#styleguide #en

2020-й год, а людям всё еще зачем-то иногда необходимы доки в PDF. Получите-распишитесь, weasyprint, тулза, которая делает красивейшего вида (примеры в скринах выше и на самом сайтике пожамкайте на дропдаун и на кнопочку) инвойсы, отчеты и билеты из HTML в PDF. Сам не пробовал, но выглядит довольно таки интересно. GitHub и Документация. Пользуемся, не болеем. Всем бодрого, по мере возможностей, дня

#tool #en

Я не пиарщик Ноушна, но больно он мне нравится, поэтому второй пост подряд именно про него. Для меня - это идеальное место в котором хочется хранить вообще всё, и рабочее и личное, бо пацаны и пацанессы сделали сервис с душой, обмазали его приятным тоном в интерфейсе, продукт очень умело говорит с юзером на его же языке. (А ещё они там недавно винтики подкрутили и на мобилах и десктопах вырос перфоманс на 40-50%)

Так вот, хоть поддержка кастомных доменов еще не реализована (а это одна из основных причин, почему предлагать документационное решение клиентам на основе Ноушна еще не оч ок), но есть небольшой хак, который немного скроет вашу шалость. Больше - в этом посте на Медиуме.

TL;DR: CloudFlare Worker / старый добрый URL Rediection. Пример - notion.community

#tool #en

Приятные новости от команды Ноушна. Тамошний дизигнер(!) накодировал(!) в качестве сайд-проекта поддержку импорта флоучартов, вайрфреймов, стики ноутов и майндмепов из Whimsical.

https://twitter.com/NotionHQ/status/1229907609970331648

#tool #en #giagram

Сорян за бомбардировку постами, но не запощу щас — забуду, близится не самая простая неделя, а так лучше вброшу сегодня и потом посреди недели буду в панике искать чем вас еще интересным покормить.

———

Лавры Grammarly очевидно многим не дают спать спокойно.

Оно и не странно, задумка лежит на поверхности, в реализации не такая уж прямо скажем и сложная, а продукт, как и парикмахеры, был, есть и будет востребован всегда — теперь у нас есть Linguix. Умеет всё то же что и Граммарли, также просит деняг, проверяет слегка хуже. Дефолтный текст из Linguix проверенный им же самим и граммарли, выводы делайте сами.

А я скажу только одно: все эти ребятки занимаются не совсем тем, что было бы полезно нам с вами, техническим писателям. Да, Граммарли круто проверяет ошибки, доставляет проёба пропущенные артикли и иногда даёт дельные советы, но нас в первую очередь интересуют другого рода правила. Давайте все вместе чаще пользоваться Vale, писать для него рулы, делиться ими, и заносить денег за Vale Server, он точно даст вам больше контроля над результатом. А при наличии кого-то, кто умеет в регулярные выражения — это просто палочка выручалочка. (но и грамарли тоже годная штука, шо уж тут)

#testthedocs #en #tool

Начнём эту неделю со СтРаНнОгО:

Некий канадец Конрад Лин предложил использовать Notion в качестве CMS-ки к блогу на GatsbyJS.

Вышло очень даже ничего, не уверен, что стоит пробовать на каком-то жизненно важном проекте, т.к (скрестил пальцы) скоро Ноуншн (усиленно обещают) выкатить свою API, вот тогда заживём!

#article #en #SSG

Скетч 2001го года с Норвежского телевидения, а актуально до сих пор и, к сожалению, будет актуально еще пару десятилетий 🤦‍♂️

Всех с праздничком и хороших выходных! ❤️

Неужели за такой буллшыт контент кому-то платят? Почему это кто-то продолжает писать? Где-то есть статистика как часто открывают и вообще делают в 2020 CHM-based, блять, хэлпы?

#example #en

Делюсь бесплатной книжечкой с contentstrategy101 про Технический контент и преобразование оного в бизнес-велью-сущность

#resource #book #en

>Slack is actually an acronym. It stands for: "Searchable Log of All Conversation and Knowledge."

Гигантский монструозный лонгридище из 7 частей от "Богов Поиска" - Algolia. Рассказывают о том как они редизайнили свою документацию, от причин зачем это всё и UI/UX решений, вплоть до самого писательства и nitty-gritty технических моментиков.

1. Redesigning Our Docs – Part 1 – Why
2. Redesigning our Docs – Part 2 – Making Technical Content Readable for Everybody
3. Redesigning Our Docs – Part 3 – The UX/UI Phase
4. Redesigning Our Docs – Part 4 – Building a Scalable CSS Architecture
5. Redesigning Our Docs – Part 5 – Building an Interactive InstantSearch Showcase
6. Redesigning our Docs – Part 6 – The processes and logistics of a large scale project
7. Redesigning our Docs – Part 7 – What’s next to come

Бонусным треком статья от них же про API документацию с посылом и о том, что счастье не в тулзах с помощью которых это всё делается, а в деньгах, которые за это платятся, а в самом подходе к структурированию этой информации и в самом контенте. Иными словами тулинг должен заботить пусть и не в последнюю очередь, но и уж точно не в первую. Adapt the tool to the content, not vice versa.

Good API Documentation Is Not About Choosing the Right Tool

#API #en #article #resource #uiux

Забыл сам, напомню теперь и вам, не используйте ie, eg и etc.

https://insidegovuk.blog.gov.uk/2016/07/20/changes-to-the-style-guide-no-more-eg-and-ie-etc/

#styleguide #en #resource