Technical Writing 101 🇺🇦
1.61K subscribers
244 photos
3 videos
12 files
418 links
Anything's A Documentation If You're Brave Enough

👋 @SuckMyNuts
Download Telegram
Я очень люблю узнавать о чужих процессах и читать о том как их строят и вообще о внутренней кухне. Недавно подвернулся сайтец 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
Пишите понятную документацию, рисуйте её значками и символами если нужно, упрощайте, и делайте всё для людей, но будто для детей, чтобы небыло вот так:

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

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

#example
Media is too big
VIEW IN TELEGRAM
Документация — не только буквы, но картинки и видео.

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

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

#video #example #en
Пятничка! 💫

В преддверии выходных можно слегка расслабиться и посмотреть как делают документацию другие.

Сегодня у нас в эфире инструкции к самой обсуждаемой железке конца 2020го года. Это то, с чем нам прийдется жить и на что смотреть изо дня в день ближайшие 4-7 лет, PlayStation 5!

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

Enjoy :}

Recommended settings:
https://youtube.com/watch?v=eMRsCR68tgQ

Using your account:
https://youtube.com/watch?v=H2DqsPh2d9k

Transfer files from PS4 to PS5:
https://youtube.com/watch?v=V8cmLeFQBT0

#example #video #visual
Что такое плохая документация? Каково пользоваться плохо задокументированным продуктом?

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

Я однажды приводил документацию Apple как хороший визуальный образец, но, как оказалось, хороша она в основном только визуально и отвечает только на базовые вопросы и показывает как работают самые простые сценарии. Если же сделать шаг влево или вправо, получается “it’s like you’re jumping off this cliff, and it’s like “good luck”. […]”

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

Если у вас есть примеры плохой документации хороших продуктов — велкам ту коммент секшн. Делитесь, жалуйтесь ну и всякое такое :}

#example #en #article
Шаблоны документации найти непросто, а хорошие шаблоны найти почти нереально.

Поэтому особенно пристально предлагаю ознакомиться с подборкой шаблонов (в Notion) на ВСЕ случаи жизни от Air!

#example #en #resource
Причины менять интерфейсный текст могут быть очень, очень разные

https://twitter.com/MichaelSteeber/status/1334619509743874052?s=20

#example #uiux
Я уже делал много постов про комиксы, так как они очень дороги сердцам всего редакторского состава и не могу обойти стороной новый комикс-гайд. В этот раз про Bash.

Прошлые комиксы в основом были от Джулии Эванс, как и вот этот вот. Она просто мастер простого и понятного визуального изложения совсем уж сложных вещей (кубернетесы, контейнеры, сеть, HTTP, Linux)

Делюсь этим не в ключе “читайте этот гайд”, а в ключе “смотрите как можно”, и не просто можно, а можно прямо КРУТО.

Bite Size Bash!

P.S:

При покупке обратите внимание на месседж под кнопкой покупки:

>Hello! It looks like you're in Ukraine, where this zine might be expensive.
>If you need it, please use this link to get 70% off the regular price.

🧡💴

#visual #example #en
Часть 1: Как написать самый мощный ворнинг в мире?

Этим вопросом, как оказалось, заняты умы множества ученых разных стран. Причина тому - ядерные отходы, а точнее их долговечность.

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

В отчете Sandia за 1993г рекомендовалось, чтобы любое такое сообщение содержало четыре уровня возрастающей сложности:

Уровень I: Элементарная информация: «Здесь что-то рукотворное»
Уровень II: Предостережение: «Здесь что-то рукотворное, и это опасно»
Уровень III: Базовая информация: рассказывает, что, почему, когда, где, кто и как
Уровень IV: Комплексная информация: подробные письменные записи, таблицы, рисунки, графики, карты и диаграммы

#example #vintage #en
Часть 2

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

- Это место - сообщение ... и часть системы сообщений ... обратите на это внимание!
- Для нас было важно отправить это сообщение. Мы считали себя могущественной культурой.
- Это место не почетное ... Здесь не отмечается никаких высокочтимых дел ... Здесь нет ничего ценного.
- То, что здесь было для нас опасным и отталкивающим. Это сообщение является предупреждением об опасности.
- Опасность находится в определенном месте ... она увеличивается к центру ... центр опасности здесь ... определенного размера и формы и ниже нас.
- Опасность все еще существует в ваше время, как и в наше время.
- Опасность для тела, это может убить.
- Форма опасности - это излучение энергии.
- Опасность возникает только в том случае, если вы существенно потревожите это место физически. Этого места лучше избегать и оставлять необитаемым.

#example #vintage #en
Часть 3

Но самой странной идеей из всех, как мне кажется, была идея из двух незамысловатых пунктов:

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

🙄

Идей нагенерено очень много, да и тема как раз для праздников, расслабить голову. + как-никак коммуникация и вроде даже "техническая”

Нашел для вас парочку годных статей как раз про вот это вот все:

Читать на Википедии
Читнуть на Vice
Глянуть на Medium

Отдельная документалка про меняющих цвет котов

#example #vintage #en
Пятничной документации пост.

Вообще сколь бы смешной эта картинка не была, как документация она отрабатывает на все сто. Тут вам и легкочитаемость и работа с аудиторией, и юморок, и эдж кейсы. Всё как надо 👀

#example #en
Для новоприбывших.

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

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

#example
Сегодня пятница, поэтому никаких серъезных лиц, просто микро-напоминание.

🖼⬆️Примерно по этой же причине _никогда_ не используйте слово “Simple” в своей документации. Чувствуйте себя журналистами, откажитесь от субъективной оценки умений читающего 🤜🤛

#example #en
Клёвый взгляд изнутри на то, как GitHub менеджит свои доки с помошью своих же Actions. Можно чего-нить подсмотреть и стырить себе или просто ознакомиться с концепцией Экшнсов.

Вот бы все большие компании были так же открыты как гитхабыч, приятно смотреть же!

🔗 Читать: How we use GitHub Actions to manage GitHub Docs

#example #knowledgemanagement
Джулия Эванс, регулярный гость в нашем уютном бложике, но на этот раз не с своими прекрасными Зинами Для Программистов, а с перечнем так-себе-паттернов затрудняющих восприятие информации и кайфовые примеры к ним.

💥паттерн 1: делать устаревшие предположения об знаниях аудитории
💥паттерн 2: наличие противоречивых ожиданий относительно знаний читателя
💥паттерн 3: натянутые аналогии
💥паттерн 4: забавные иллюстрации на сухих объяснениях
💥паттерн 5: нереалистичные примеры
💥паттерн 6: жаргон, который ничего не значит
💥паттерн 7: отсутствует ключевая информация
💥паттерн 8: вводится слишком много концепций одновременно
💥паттерн 9: начинаете абстрактно
💥паттерн 10: неподдерживаемые ничем утверждения
💥паттерн 11: нет примеров
💥паттерн 12: объяснять «неправильный» способ сделать что-то, не говоря, что это неправильно
💥паттерн 13: «что» без «почему»

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

🔗 Читать: Patterns in confusing explanations

#visual #en #example
Наткнулся на приятную заметку о любви к старым бумажным мануалам к, собственно, старому софту и железу. Я сам питаю неаргументированную любовь к старым инструкцияминструкциям к древним военным штуковинам), что-то в них такое есть. Эта статья поняла чётче осознать чем они так манят и почему они читаются и выглядят намного приятнее, чем практически любая современная инструкция.

Рекомендую, короткое спокойное чтиво на 5-6 минут, но сколько же души в этом всём. Может и вы откроете в себе любовь к “ископаемым”.

🔗 Читать: Why I collect and read old computer manuals

#visual #vintage #example #en
👅 Языки:

#ru | #en

👷 Карьера:

#career — советы и всемозможные статьи о карьере техписателя
#conference — техписательские конференции, их записи и заметки
#resources — ресурс для саморазвития
#article — полезная статья, которая учит чему-то клёвому, что позволит стать более лучшим писателем
#vacancy — интересная вакансия или что-то связанное с наймом
#video — видео, видос, видосичек, видосюлька. И подкасты!
#book — книга/хендбук
#courses — курсы, программы для технических писателей

🛠 Технологии:

#tool — полезная утилита/приложение
#changelog — все о чейнджлогах, примеры, правила
#markdown — все о языке разметки Markdown
#reStructuredText — все о языке разметки reStructuredText
#asciidoc — все о языке разметки asciidoc
#LaTeX — все систему набора и вёрстки и язык разметки LaTeX
#ide — среды разработки и все что с ними связано
#vscode — все о Visual Studio Code, настройка, плагины, хитрости
#SSG — JAMStack, генераторы статических сайтов, Hugo, Jekyll, Antora, etc.
#testthedocs — тестирование документации, линтинг
#API — про документирование API, примеры, лайфхаки, подсказки
#diagram — про диаграммы (много про diagrams as a code), mermaid, UML
#screenshot — все про скриншоты, утилиты, сервисы и красивенькие фотоснимки экрана
#ai — про GPT, GitHub Copilot и прочее, где ИИ помогает нам писать

🧺 Общее:

#tonevoice — о правилах общения в документации
#language — что-то конкретно о языке, в основном английский
#legal — юридическая документация, лицензии
#styleguide — все о стилях и правилах
#DocsAsCode — все про подход к документации как к коду
#example — примеры документации (хорошие и плохие)
#uiux — интерфейсы, текст в интерфейсах, пользовательский опыт
#knowledgemanagement — менеджмент знаний, хранилища, тулзы, техники, советы и наблюдения
#versioning — про версионирование
#accessibility — все об аксессебилити в документации
#checklist — чеклист/шпаргалка
#vintage — винтажная документация, старые компьютеры, софт, техника, игры
#visual — про визуальную составляющую документации
#metrics — все о метриках документации
#random — что-то совсем косвенно относящееся к техписательству, юморески

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

Comics as Documentation частый гость на нашем канале, сегодня у нас и художница и программист Tomomi Imura c котиками и git-коммандами

P.S Ну и пока мы на визуальной теме, предлагаю вам ознакомиться с серией скетч-заметой с недавней конференции Write the Docs Prague. Можете полистать эти заметки и так решить какой из докладов вам интереснее послушать/посмотреть (<-- тут ссылка на ютубный плейлист Пражской конфы) полностью:

1. Creating documentation for the African audience.
2. Toward the broader globalization of Open Source: documenting your localisation Journey
3. Improve Customer Adoption with UI Help
4. The Art of Asking Questions
5. Cultivating a Stakeholder Network for Our Docs: How Building Relationships Improves Our Content
6. Beyond spell checking - what else can we check automatically?
7. Documentation as Marketing? From Conflict to Collaboration
8. Maintaining Documentation: Make It Easy!
9. How I convinced my boss to build our docs team
10. ADHD and its impact on the Creative Process for Writers
11. Two years of Markdoc: what we’ve learned about balancing developer and author experience

🔗 Читать: GIT PURR! Git Commands Explained with Cats!

#en #visual #example