Всем привет!
Иксолла открыла прием заявок на направление Documentation в рамках Xsolla School 2021!
В этом году впервые организовано два потока:
– Базовый (количество участников не ограничено): для тех, кто хочет познакомиться с основными понятиями и принципами документации.
– Профильный (только 15 участников): для тех, кто уже знает основы работы с документацией и хочет прокачать профессиональные навыки.
На школе вы научитесь писать документацию, которую реально будут читать, начнете понимать особенности ГОСТов и стайлгайдов, узнаете специфику подготовки контента для UI/UX веб-приложений и многое другое!
Обучение в школе полностью бесплатное. Прочитать подробности и пройти регистрацию можно по ссылке: https://rb.gy/wftbg5
Иксолла открыла прием заявок на направление Documentation в рамках Xsolla School 2021!
В этом году впервые организовано два потока:
– Базовый (количество участников не ограничено): для тех, кто хочет познакомиться с основными понятиями и принципами документации.
– Профильный (только 15 участников): для тех, кто уже знает основы работы с документацией и хочет прокачать профессиональные навыки.
На школе вы научитесь писать документацию, которую реально будут читать, начнете понимать особенности ГОСТов и стайлгайдов, узнаете специфику подготовки контента для UI/UX веб-приложений и многое другое!
Обучение в школе полностью бесплатное. Прочитать подробности и пройти регистрацию можно по ссылке: https://rb.gy/wftbg5
❤1
Если вы только начали открывать для себя линтеры простого нашего с вами языка, то предлагаю к ознакомлению отличный интродакшн в Vale.
Объясняют и в чем отличие от линтеров кода, и этимологию самого слова, и даже делятся ссылочкой на Vale Studio, которой я совсем забыл с вами поделиться. Vale Studio это бесплатный веб-бейзд редактор, который позволяет легко создавать и тестировать новые правила. Очень тесно интегрирован с regex101.
🔗 Читать: First steps with the Vale prose linter
#tool #testthedocs #en #article
Объясняют и в чем отличие от линтеров кода, и этимологию самого слова, и даже делятся ссылочкой на Vale Studio, которой я совсем забыл с вами поделиться. Vale Studio это бесплатный веб-бейзд редактор, который позволяет легко создавать и тестировать новые правила. Очень тесно интегрирован с regex101.
🔗 Читать: First steps with the Vale prose linter
#tool #testthedocs #en #article
❤1
Иногда нужно быстро “поиграться текстом” на уже запаблишеном материале, будь-то заголовок, подзаголовок или какая-то сноска. Что мы все делаем обычно в таком случае? Конечно же, идем в ДевТулзы браузера и ковыряем буквы там. Но, скажем честно, процесс не самый магический и завораживающий, поэтому от него хотелось бы отказаться в пользу чего-нить поудобнеé.
Наткнулся на приятный плагинчик для (извините пользователи Firefox) Chromium-based браузеров, который превращает любой текст в готовый для редактирования
Пользуйтесь на здоровье: Polishapp 💅
#tool #visual #en
Наткнулся на приятный плагинчик для (извините пользователи Firefox) Chromium-based браузеров, который превращает любой текст в готовый для редактирования
Пользуйтесь на здоровье: Polishapp 💅
#tool #visual #en
❤1
🚶♀️ Набрёл тут на советы для пишущих от Amazon (если кто знает, где взять фулл — напишите в комментариях).
Многое уже всем знакомо, особенно если вы проходили Гугловый курс по TW, но лишним, как вы помните, повторение не бывает.
🎺 Bonus Track: 🎺
Очень детальный рассказ о структуре “Амазононовского Шестистраничника”. Это Джефф Безос невзлюбил скучные паверпойнт презентации и заставил всех писать вразумительные, легкочитаемые и усвояемые narrative- и data-driven отчеты. Ну короче, как раз то, что нам с вами нужно.
🔗 Читать: The Anatomy of an Amazon 6-pager
#article #en
Многое уже всем знакомо, особенно если вы проходили Гугловый курс по TW, но лишним, как вы помните, повторение не бывает.
🎺 Bonus Track: 🎺
Очень детальный рассказ о структуре “Амазононовского Шестистраничника”. Это Джефф Безос невзлюбил скучные паверпойнт презентации и заставил всех писать вразумительные, легкочитаемые и усвояемые narrative- и data-driven отчеты. Ну короче, как раз то, что нам с вами нужно.
🔗 Читать: The Anatomy of an Amazon 6-pager
#article #en
❤1
Стоит ли использовать в документации обращение от первого лица множественного числа?
Наверняка во время написания технической документации, у вас возникала мысль использовать: “we”, “us”, и “ours”. Но в отличие от второго лица (“you”), использование “we” не так явно распространено или приемлемо.
Но не все так просто! Статья углубляется в вопрос использования “we” и кроме того, автор сравнивает как разные стайлгайды советуют поступать с вот этим вот всем.
🔗 Читать: Should you use the first-person plural in your documentation?
#language #en
Наверняка во время написания технической документации, у вас возникала мысль использовать: “we”, “us”, и “ours”. Но в отличие от второго лица (“you”), использование “we” не так явно распространено или приемлемо.
Но не все так просто! Статья углубляется в вопрос использования “we” и кроме того, автор сравнивает как разные стайлгайды советуют поступать с вот этим вот всем.
🔗 Читать: Should you use the first-person plural in your documentation?
#language #en
❤1
💡Мечтать не вредно, но и вредно не мечтать, или сказ об идеальных митингах.
Недавно я выкладывал пост про “Амазоновский Шестистраничник” (звучит как что-то из урбандикшнари, да), а теперь пришло время еще немного расширить границы познания о культуре документации в Amazon, ибо она крутая.
Это, по моему мнению, идеальнейший из раскладов, когда вам необходимо синхронизировать знания большого круга людей на регулярной основе и поддерживать их вовлеченность в новое на проекте.
И в чем же секрет, спросите вы? Конечно же в чтении документации! Но ее и так читают, скажете вы? Как бы не так! Но тут речь идет о >document-based-митингах<, начинаются которые с (нет, вы только представьте) коллективного чтения документа.
В чем автор поста видит проблему обычных митингов:
- Никто не читал письма / документы, и приходилось все объяснять на митинге;
- Некоторые люди таки читали документ, но забыли, что в нем говорилось, потому что прочитали его за несколько дней или часов до митинга;
- По крайней мере, у одного человека был вопрос, на который можно было бы ответить по электронной почте.
Несмотря на гору плюсов, выделять от 10 минут до получаса только на чтение документа, а в случае с шестистраничником, так и еще больше, может позволить себе далеко не каждая команда/компания. Но с другой стороны, к митингам можно больше не готовиться. 🤷
Вообще, это довольно необычный в современных реалих, но, кажется, очень эффективный подход. И я, как и автор статьи, могу представить, что примерно все мои места работ стали бы только лучше с таким подходом к документам и митингам.
И запомните, if there isn’t a doc there isn’t a meeting
🔗 Читать: The Document Culture of Amazon
#article #en
Недавно я выкладывал пост про “Амазоновский Шестистраничник” (звучит как что-то из урбандикшнари, да), а теперь пришло время еще немного расширить границы познания о культуре документации в Amazon, ибо она крутая.
Это, по моему мнению, идеальнейший из раскладов, когда вам необходимо синхронизировать знания большого круга людей на регулярной основе и поддерживать их вовлеченность в новое на проекте.
И в чем же секрет, спросите вы? Конечно же в чтении документации! Но ее и так читают, скажете вы? Как бы не так! Но тут речь идет о >document-based-митингах<, начинаются которые с (нет, вы только представьте) коллективного чтения документа.
В чем автор поста видит проблему обычных митингов:
- Никто не читал письма / документы, и приходилось все объяснять на митинге;
- Некоторые люди таки читали документ, но забыли, что в нем говорилось, потому что прочитали его за несколько дней или часов до митинга;
- По крайней мере, у одного человека был вопрос, на который можно было бы ответить по электронной почте.
Несмотря на гору плюсов, выделять от 10 минут до получаса только на чтение документа, а в случае с шестистраничником, так и еще больше, может позволить себе далеко не каждая команда/компания. Но с другой стороны, к митингам можно больше не готовиться. 🤷
Вообще, это довольно необычный в современных реалих, но, кажется, очень эффективный подход. И я, как и автор статьи, могу представить, что примерно все мои места работ стали бы только лучше с таким подходом к документам и митингам.
И запомните, if there isn’t a doc there isn’t a meeting
🔗 Читать: The Document Culture of Amazon
#article #en
❤1
Notion запустил Synced Blocks!
Вместо того, чтобы обновлять один и тот же кусок документа в миллионе мест, теперь можно создать Synced Block и ссылаться на него в любом другом месте, а изменения подтянутся :3
P.S
Ссылочка, собсно, на блогпост с историей формата, небольшим экскурсом в 60-е и ходом мысли по ходу разработки фичи
#tool #en
Вместо того, чтобы обновлять один и тот же кусок документа в миллионе мест, теперь можно создать Synced Block и ссылаться на него в любом другом месте, а изменения подтянутся :3
P.S
Ссылочка, собсно, на блогпост с историей формата, небольшим экскурсом в 60-е и ходом мысли по ходу разработки фичи
#tool #en
❤1
💰 Подъехали результаты опроса по зарплатам Техписателей за 2020 год.
🔗 Читать: Write the Docs Salary Survey 2020 Results
#career #en
🔗 Читать: Write the Docs Salary Survey 2020 Results
#career #en
❤1
Kathy Korevec, Продукт Манагер из GitHub, написала занимательнейшую статью с просто горооой размышлений о том, как улучшить документацию в GitHub. Кроме того, она нагенерировала еще ведро идей о том, как оптимизировать документацию для разработчиков, и подкрепила их мокапами. Говорит о необходимости “многоформатности” документации, об оптимизации поиска, в общем очень интересный взгляд внутрь головы продукт манагера довольно таки большой компании, рекомендуется к прочтению.
🔗Читать: Maybe it’s time we re-think docs
#article #en
🔗Читать: Maybe it’s time we re-think docs
#article #en
❤1
И мы плавно возвращаемся из отпуска! Stay tuned..накопилось много годноты.
Да, иногда даже на Хабре бывает полезный и читабельный контент.
Kiii~nda саксесс стори с (пере)построением базы знаний, которая действительно работает и выполняет свои задачи, а еще все это дело в Notion.
Если вам предстоит или хотя бы маячит на горизонте задача по организации обще компанейской (или хотя бы конкретного отдела) базы знаний, непременно стоит ознакомиться. Автор в относительно сжатые сроки активно покусал кактус, но все же смог, прочитайте и вы, чтобы если и кусать, то хотя бы с другой стороны.
Ждем продолжение, ну а пока, всем хорошего старта рабочей недели 🙏
🔗 Читать: Как (не) нужно строить базу знаний для проекта с нуля. Часть Первая, утопическая
#knowledgemanagement #ru #article
Kiii~nda саксесс стори с (пере)построением базы знаний, которая действительно работает и выполняет свои задачи, а еще все это дело в Notion.
Если вам предстоит или хотя бы маячит на горизонте задача по организации обще компанейской (или хотя бы конкретного отдела) базы знаний, непременно стоит ознакомиться. Автор в относительно сжатые сроки активно покусал кактус, но все же смог, прочитайте и вы, чтобы если и кусать, то хотя бы с другой стороны.
Ждем продолжение, ну а пока, всем хорошего старта рабочей недели 🙏
🔗 Читать: Как (не) нужно строить базу знаний для проекта с нуля. Часть Первая, утопическая
#knowledgemanagement #ru #article
❤1
🔥 Небольшой мотивационный пост, приуроченный к красивому числу подписчиков!
Спасибо, что вы есть 😘
Мы тут не постоянно, но регулярно напоминаем себе, как важны техписы, и что нас всех стоит ценить.
Да, пока приходится гладить себя по голове самим, но с каждым годом ситуация становится все лучше и лучше, а осознанность работодателей видна всё явнее и явнее.
В статье есть парочка греющих душу цитат и немного зарплатной аналитики, но на нас с вами она, как обычно, ложится не очень хорошо.
И помните, it doesn’t matter how great your software is if nobody understands how or why they should use it 👆
🔗 Читать: The uber-importance of docs
#article #en
Спасибо, что вы есть 😘
Мы тут не постоянно, но регулярно напоминаем себе, как важны техписы, и что нас всех стоит ценить.
Да, пока приходится гладить себя по голове самим, но с каждым годом ситуация становится все лучше и лучше, а осознанность работодателей видна всё явнее и явнее.
В статье есть парочка греющих душу цитат и немного зарплатной аналитики, но на нас с вами она, как обычно, ложится не очень хорошо.
И помните, it doesn’t matter how great your software is if nobody understands how or why they should use it 👆
🔗 Читать: The uber-importance of docs
#article #en
❤1
При сравнении продуктов, вы хотите понять, какой все же из них лучше? Тем не менее мы часто забываем оценить документацию по проекту. Проект может предлагать отличный набор функций, но в то же время у него может не быть простой в использовании документации. Это может отрицательно сказаться на процессе использования продукта и эффективности вашей команды. Автор статьи предлагает, пусть и без откровений, научиться оценивать UX документации (со стороны разработчиков).
🔗 Читать: Developer Experience: How to Define Good Documentation?
#article #en
🔗 Читать: Developer Experience: How to Define Good Documentation?
#article #en
❤1
Немного апдейтов из мира стайлгайдов:
1. Google обновил часть своего стайлгайда про заголовки.
2. GitHub добавили раздел с правилами по написанию гендерно-нейтральной документации в свои гайдлайны.
#styleguide #en
1. Google обновил часть своего стайлгайда про заголовки.
2. GitHub добавили раздел с правилами по написанию гендерно-нейтральной документации в свои гайдлайны.
#styleguide #en
❤1
Джулия Эванс, регулярный гость в нашем уютном бложике, но на этот раз не с своими прекрасными Зинами Для Программистов, а с перечнем так-себе-паттернов затрудняющих восприятие информации и кайфовые примеры к ним.
💥паттерн 1: делать устаревшие предположения об знаниях аудитории
💥паттерн 2: наличие противоречивых ожиданий относительно знаний читателя
💥паттерн 3: натянутые аналогии
💥паттерн 4: забавные иллюстрации на сухих объяснениях
💥паттерн 5: нереалистичные примеры
💥паттерн 6: жаргон, который ничего не значит
💥паттерн 7: отсутствует ключевая информация
💥паттерн 8: вводится слишком много концепций одновременно
💥паттерн 9: начинаете абстрактно
💥паттерн 10: неподдерживаемые ничем утверждения
💥паттерн 11: нет примеров
💥паттерн 12: объяснять «неправильный» способ сделать что-то, не говоря, что это неправильно
💥паттерн 13: «что» без «почему»
Даже если все выглядят до боли знакомо, сходите почитайте примеры и развернутые описания почему это плоховасто
🔗 Читать: Patterns in confusing explanations
#visual #en #example
💥паттерн 1: делать устаревшие предположения об знаниях аудитории
💥паттерн 2: наличие противоречивых ожиданий относительно знаний читателя
💥паттерн 3: натянутые аналогии
💥паттерн 4: забавные иллюстрации на сухих объяснениях
💥паттерн 5: нереалистичные примеры
💥паттерн 6: жаргон, который ничего не значит
💥паттерн 7: отсутствует ключевая информация
💥паттерн 8: вводится слишком много концепций одновременно
💥паттерн 9: начинаете абстрактно
💥паттерн 10: неподдерживаемые ничем утверждения
💥паттерн 11: нет примеров
💥паттерн 12: объяснять «неправильный» способ сделать что-то, не говоря, что это неправильно
💥паттерн 13: «что» без «почему»
Даже если все выглядят до боли знакомо, сходите почитайте примеры и развернутые описания почему это плоховасто
🔗 Читать: Patterns in confusing explanations
#visual #en #example
❤1
Давно мы что-то про тулзы не говорили (а ничего нового, кроме очередного yet another best-on-the-market markdown editor не выдумали). Но мы то знаем, какой редактор нужен техписателю, и нет, это не Microsoft Word, это, конечно же, VS Code.
Так вот, если вы на острие, так сказать, технологий и мейнтейните какой-то статический сайтик, вы могли заметить, что уследить за всем контентом бывает сложно, поэтому некий товарищ упростил всем нам жизнь и сделал пусть и не гейм чейнджер расширение для VS Code, но приятную мелочь, как минимум.
Front Matter — это такая себе локальная headless CMS для менеджмента ваших статических сайтиков (цитата: Hugo, Jekyll, Hexo, NextJs, Gatsby, and many more), который еще и кастомными скриптами можно расширять, лепота. Все, что дополнение умеет, можно глянуть в доках.
#tool #markdown #SSG
Так вот, если вы на острие, так сказать, технологий и мейнтейните какой-то статический сайтик, вы могли заметить, что уследить за всем контентом бывает сложно, поэтому некий товарищ упростил всем нам жизнь и сделал пусть и не гейм чейнджер расширение для VS Code, но приятную мелочь, как минимум.
Front Matter — это такая себе локальная headless CMS для менеджмента ваших статических сайтиков (цитата: Hugo, Jekyll, Hexo, NextJs, Gatsby, and many more), который еще и кастомными скриптами можно расширять, лепота. Все, что дополнение умеет, можно глянуть в доках.
#tool #markdown #SSG
❤1