Держите подборку гугловских стайгайдов, посмотрите как взрослые дяди делают (C++ Style Guide, Objective-C Style Guide, Java Style Guide, Python Style Guide, R Style Guide, Shell Style Guide, HTML/CSS Style Guide, JavaScript Style Guide, AngularJS Style Guide, Common Lisp Style Guide, and Vimscript Style Guide)

https://google.github.io/styleguide/

#styleguide #en

Пример краткого и красивого Writing Guide'a от DigitalOcean:

https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines#style

#styleguide #en

О важности стайлгайдов

https://twitter.com/qikipedia/status/1161578207654506498?s=19

#styleguide #en #article

Небольшая подборка гайдов o том, как создавать доступный (в плане Accessible) контент:


Google: https://developers.google.com/style/accessibility

Microsoft: https://docs.microsoft.com/en-us/style-guide/accessibility/accessibility-guidelines-requirements

IBM: https://www.ibm.com/developerworks/library/styleguidelines/index.html

Wikipedia: https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Accessibility

У Web AIM есть хорошие статьи для изучения аксессебилити в вебе в целом: https://webaim.org/

#accessibility #article #styleguide #en

Руководство по Читабельности от Content Design London — это:

- Ответы на 17 приоритетных вопросов по читабельности;
- Более 80 рекомендаций по читабельности: топовейший Readability Checklist;
- Всякое полезное по юзабилити-тестированию.

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

#aceccibility #resource #article #en #styleguide

Забыл сам, напомню теперь и вам, не используйте 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

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

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

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

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

#styleguide #en

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

#styleguide #en #article

↓↓↓↓↓↓↓↓

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

- 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

One stop shop по вопросам стайлгайдов, tone of vocie и accessibility (там еще очень много про брендирование, код, дизайн системы, но нам это не очень релевантно). Очень солидная подборка, дальше этого сайта можно не ходить

http://styleguides.io/

#styleguide #en

Немного апдейтов из мира стайлгайдов:

1. Google обновил часть своего стайлгайда про заголовки.
2. GitHub добавили раздел с правилами по написанию гендерно-нейтральной документации в свои гайдлайны.

#styleguide #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 — что-то совсем косвенно относящееся к техписательству, юморески

Предлагайте новые хэштеги в комментариях!

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

Следующая секция стайлгайда “Writing inclusive content” учит как не ненароком не обидеть своего читателя. Она довольно базовая, поэтому предлагаю взглянуть на отдельную статью про настройку своего линтера, которая помогает как раз находить такие узкие места в вашей документации.

Читать:
[1] New Relic Style Guide + 5 questions
[2] Reducing negative and biased language in documentation

#testthedocs #styleguide #voicetone #en #tool #language