Вывод: опозориться можно и в документации, состоящей из одного слова и одной картинки. Иногда (при неумении/неопытности - всегда) лучше не креативить, а писать как есть. Только узнав и научившись как делать нужно, можно начать делать так, как хочется и гнуть (ну ладно, more like подгибать) правила под себя.

Hint: чтобы посмотреть правильный ответ, нажмите на 💡

#example

Я очень люблю узнавать о чужих процессах и читать о том как их строят и вообще о внутренней кухне. Недавно подвернулся сайтец Greater Greater Washington, на котором чуваки на волонтёрской основе топят за все хорошее и против всего плохого в своем округе, улучшают район и всячески его развивают.

Кроме оффлайн активностей, товарищи ведут активный блог и ведут его основательно, у них даже есть свой стайлгайд, и они даже его опубликовали. Да, он не технический, но полезно и интересно посмотреть на чужую работу.

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

Это пример отличной коммуникации и knowledge sharing attitude, будьте как Greater Greater Washington!

#example #career #en

ReadMe (которые personalized, interactive developer hubs) ведут офигенский documentation-related блог, рекомендую!

Сегодня попалась на глаза их обширная статья о том как начать вкатываться в Swagger + OpenAPI документацию. Темплейты, бест поактисы, тулзы и примеры. Всё к вашим услугам! Нормально подойдет для базовых познаний что там да как.

Бонус трек - Mockoon, мокалка API, которая умеет всё локально (No remote deployment, no account required, open source.), еще и кроссплатформенная.

#API #example #resource #article #en

К вопросу о том как выпрыгнуть из цикла Нужна работа --> Для работы нужен опыт --> Для опыта нужна работа. Получить хоть какое-то портфолио для начала карьеры в техписательстве или просто помочь сообществу если есть пара свободных часов в день вполне реально.

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

Пост оч грамотно структурирован, а что главное - есть ссылка на "How to Contribute to Open Source for first-timers and for veterans."

#vacancy #career #en

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

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

Ключевые моментики из статьи:

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

Бонусный трек: их же статья про ценность документации и сколько может стоить отказ от обмена знаниями.

#article #en #resource

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

- Microsoft Writing Style Guide
- Google Developer Documentation Style Guide
- Apple Style Guide
- DigitalOcean Product Documentation Style Guide
- GitHub Style Guide
- GitLab Docs Documentation Style Guide
- Mailchimp Content Style Guide
- RedHat Style Guide
- Rackspace Style Guide for Technical Content
- Splunk Style Guide

Другие полезные стайлгайды:

- Federal plain language guidelines (USA)
- IEEE Editorial Style Manual for Authors
- IBM developerWorks editorial style guide
- Online Writing Lab (OWL) at Purdue University
- Paramedic Method: A Lesson in Writing Concisely
- University of Oxford Style Guide
- The Diversity Style Guide
- Progressive’s Style Guide

#styleguide #en

Тут наше любимое! Статейка чтоб была под рукой в следующий спор

Функционал или функциональность 

Пишете про технологии, стартапы и приложения — статья точно поможет поставить жирную точку в этом споре:
 
https://nepishi.ru/s/function/

Залежалась в закладках статья (статья старая, кидал вам её сюда еще в 2018, а перевод свежий 🇷🇺) про UX Writing от Гугла.

Статья особенно полезна примерами как делать и как не.

Там и про бренд войс и про тон и, собственно, очень полезный чеклист, чтобы ничего не упустить! Если не осилили её на английском, крайне советую прочитать сейчас

#uiux #ru #en #article

Пишите понятную документацию, рисуйте её значками и символами если нужно, упрощайте, и делайте всё для людей, но будто для детей, чтобы небыло вот так:

https://twitter.com/jaredpalmer/status/1293537083399839744?s=20

Всем хорошей пятницы и приятных выходных

#example

Пост заслуживает внимания! Это очень крутой учебник!

#knowledgemanagement #ru #book

↓↓↓↓↓↓↓↓

Управления знаниями пост

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

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

Далеко не всё ещё оформлено, у нас огромный бэклог с полезным контентом, но уже сейчас можно посвятить время изучению гайда, поделиться с коллегами и положить сайт в закладки.

✊🏼 Хороший стартовый набор для начинающих UX-писателей

Основные термины, принципы, инструменты, книги и статьи. Поможет сориентироваться в теме и наметит следующие шаги в изучении.

https://gathercontent.com/blog/content-101-ux-writing

Немного о подсознательном восприятии.

Вчера наткнулся на вот такой вот твит: https://twitter.com/notdetails/status/1298349462440607750?s=19

Вообще довольно интересное наблюдение и явно проверенное опытом и временем, и кучей боли.

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

Бонус треком - Lightning Talk с Write the Docs Portland 2020 как раз об уместности нарушения некоторых правил: https://youtu.be/HIfANztn_-A

#language #en #article

Мне очень нравится идея Plain English, и я планирую периодически вам об этом напоминать. Из plain ("простых") принципов Английского можно почерпнуть очень много полезного для нашей профессии, у них на сайте даже слоган: "Fighting for crystal-clear communications since 1979".

Чем это может быть полезно? Ну, например можно изучить конструкции построения приложения, брать наборы стоп-слов, которыми можно пополнить свои линтеры, чтобы они в будущем выдавали ворнинги. Можно настроить свою среду разработки так, чтобы она уведомляла вас, когда предложение становится "сложным" или же слишком длинным. Сотни профитов!

http://www.plainenglish.co.uk/how-to-write-in-plain-english.html

P.S Спешу заметить, что (по моему мнению, конечно) в современном техрайтинге одним plain English (то же самое применимо и к русскому) сыт не будешь. Можно сколь угодно "просто" и без ошибок писать, но без той самой доли "индивидуальности" документация и инструкции так и будут теми самыми бумажками, которые при покупке телефона или любой другой техники все выкидывают. Я бы хотел, чтобы документация была не только понятной, но и не унылой, как защита курсовой

#language #en

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

Я постараюсь сконцентрироваться на более технических вещах или лингвистических. Больше про стратегии, SSG, линтеры, инклюзивность, a11y, information architecture, и намного меньше про базу.

Я уже когда-то кидал сюда этот хендбук, но уж очень он хорош в качестве введения, смело отправляйте вопрошающим "как вкатиться, что надо уметь" и всякое такое:

https://www.dozuki.com/hubfs/PDFs/Dozuki_Tech_Writing_Handbook.pdf

#career #en #SSG #accessibility

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

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

Paircast — комбинация всего вышеперечисленного, но в единой обёртке. Во время работы Paircast записывает экран, микрофон и камеру, как скринкаст.

Видеоуроки - не лучший формат для (изучения) программирования скажете вы. Видео не индексируются и там нельзя сделать там ctrl+f, нельзя копировать и вставлять. Но не всё так просто.

Под капотом у Paircast живёт git, который отслеживает изменения файлов и согласовывает их со скринкастом. Измененный код отображается как git diff'ы в markdown файле рядом с видео, там же и показана транскрипция всего, что вы говорите.

Посмотрите как это выглядит в действии на офсайте.

Проект еще в бете, но доступ можно получить постучавшись к ним в Discord.

Документация — не только буквы, но картинки и видео.

Тут недавно слили внутреннее обучающее видео прямиком из Apple. На видео учат сотрудником Apple Maps как подготовить машину с камерой к съемке, как эту съемку осуществлять и всякое такое. Не забыли даже напомнить о перекусе во время работы 🍟

Небольшой такой взгляд в закулисье knowledge sharing’a в Apple и на их внутренние тулзы. Если было интересно каково оно в гугломашинке — уверен, примерно также.

#video #example #en

Кайфовый Твиттер-тред про то, как доносить (и как разные продукты/компании это делают) изменения в продукте до конечного пользователя. В треде собрано очень много и хороших и плохих примеров:

https://twitter.com/scottkubie/status/1064981319472553985?s=20

#changelog #en #article

Spotify выпустили TechDocs, плагин для собственного (опенсорсного) дев-портала Backstage.

Там полный набор: docs-as-code, Markdown, MkDocs, простое создание GitHub ишьюсов, поддержка Slack и прочие приятности (но, конечно, если вы готовы перебраться на Backstage).

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

#tool #en