💡Мечтать не вредно, но и вредно не мечтать, или сказ об идеальных митингах.
Недавно я выкладывал пост про “Амазоновский Шестистраничник” (звучит как что-то из урбандикшнари, да), а теперь пришло время еще немного расширить границы познания о культуре документации в 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
Продолжим марафон тулз.
Часто наблюдаю, как невольные пользователи Confluence хотят причаститься к чему-то посовременнее, и, например, линтить текст в VS Code и писать в Markdown. Но как все это дело потом впихнуть в Конфу? Копипаст это скучно и к тому же утомительно.
А хочется чего-то большего, хочется git blame, хочется не кривую и скудную нативную историю изменений Confluence, а простых человеческих пуллреквестов. А может у вас даже появлялись мысли о Continuous Integration? Fear not, теперь все это можно, некий Egor Kovetskiy уже довольно давно девелопит и регулярно обновляет прекрасную тулзу под названием Mark.
Марк позволяет делать все вышеперечисленное, для этого вам просто нужно слегка сбрызнуть ваши .md файлы html-лайк метадата хэдерами и запустить миниатюрный бинарник на Go (отдельный респект).
Почитать больше можно в официальном блогпосте 🔗Use Markdown for Confluence и в соответствующем 🔗репозитории проекта.
#tool #en #markdown
Часто наблюдаю, как невольные пользователи Confluence хотят причаститься к чему-то посовременнее, и, например, линтить текст в VS Code и писать в Markdown. Но как все это дело потом впихнуть в Конфу? Копипаст это скучно и к тому же утомительно.
А хочется чего-то большего, хочется git blame, хочется не кривую и скудную нативную историю изменений Confluence, а простых человеческих пуллреквестов. А может у вас даже появлялись мысли о Continuous Integration? Fear not, теперь все это можно, некий Egor Kovetskiy уже довольно давно девелопит и регулярно обновляет прекрасную тулзу под названием Mark.
Марк позволяет делать все вышеперечисленное, для этого вам просто нужно слегка сбрызнуть ваши .md файлы html-лайк метадата хэдерами и запустить миниатюрный бинарник на Go (отдельный респект).
Почитать больше можно в официальном блогпосте 🔗Use Markdown for Confluence и в соответствующем 🔗репозитории проекта.
#tool #en #markdown
❤1
Тревожные (на самом деле не очень) вести с полей JAMStack. Автор поста «RIP Jekyll (The Genesis of the Jamstack)» переживает, что Джекилл отжил свое и пора двигаться дальше. Пост немного надуманный, отчасти истеричный, да и прямых доказательств и заявлений разработчиков не особо-то и было.
Мой пойнт скорее в том, что хорошо бы научиться орудовать несколькими утилитами/языками/фреймворками/подходами, которые более-менее актуальны в вашей сфере сегодня. Остаться за бортом технологического прогресса довольно легко, и в нашей с вами области это отлично видно по количеству пользователей всяких DITA, MadCap Flare, Word и иже с ними.
🔗 Читать: RIP Jekyll (The Genesis of the Jamstack)
#SSG #en #article
Мой пойнт скорее в том, что хорошо бы научиться орудовать несколькими утилитами/языками/фреймворками/подходами, которые более-менее актуальны в вашей сфере сегодня. Остаться за бортом технологического прогресса довольно легко, и в нашей с вами области это отлично видно по количеству пользователей всяких DITA, MadCap Flare, Word и иже с ними.
🔗 Читать: RIP Jekyll (The Genesis of the Jamstack)
#SSG #en #article
❤1
Forwarded from Нац Нац
Немного о построении культуры документации на примере трёх IT-гигантов: Google, Twitter, Spotify.
В статье собраны не сколько хорошие примеры и решения проблем, сколько подборка ссылок на сами доклады, где тогдашние техписы рассказывают как они строили и/или укрепляли культуру документирования. Довольно таки познавательно, изнаночка больших компаний это как заглянуть в тетрадку к отличнику
🔗 Читать: How Google, Twitter, and Spotify built a culture of documentation
В статье собраны не сколько хорошие примеры и решения проблем, сколько подборка ссылок на сами доклады, где тогдашние техписы рассказывают как они строили и/или укрепляли культуру документирования. Довольно таки познавательно, изнаночка больших компаний это как заглянуть в тетрадку к отличнику
🔗 Читать: How Google, Twitter, and Spotify built a culture of documentation
❤1
Ситуация: вас наняли техническим писателем в недавно основанную или недавно очнувшуюся и требующую доки компанию. В ней нет ни-че-го (из документации), а должно быть очень многое. За что браться, куда бежать и как определить, что должно быть в Minimum Viable Documentation?
Очень информативный лонгрид под слоганом «Get from nothing to something with MVD» поможет не запаниковать и ответить на все вопросы выше.
🔗 Читать: From Nothing to Something with Minimum Viable Documentation
#article #en
Очень информативный лонгрид под слоганом «Get from nothing to something with MVD» поможет не запаниковать и ответить на все вопросы выше.
🔗 Читать: From Nothing to Something with Minimum Viable Documentation
#article #en
❤1
Forwarded from Нац Нац
Write the Docs проводит третий ежегодный зарплатный опрос.
Результаты всегда интересно изучить, узнать среднюю температуру по больнице, возможно, показать инфу работодателю, а то и задуматься о смене локации проживания и/или индустрии.
Вот, что говорят о целях и пользе авторы опроса:
«We hope this data helps our community members determine what appropriate salary ranges are, and provide a benchmark for future employment-related decisions and negotiations.
Additionally, we’re hoping the results spark discussion of employment-related trends and issues in our industry, including but not limited to the effects of the COVID-19 pandemic.»
🔗 Заполнить Documentation Salary Survey 2021
Результаты всегда интересно изучить, узнать среднюю температуру по больнице, возможно, показать инфу работодателю, а то и задуматься о смене локации проживания и/или индустрии.
Вот, что говорят о целях и пользе авторы опроса:
«We hope this data helps our community members determine what appropriate salary ranges are, and provide a benchmark for future employment-related decisions and negotiations.
Additionally, we’re hoping the results spark discussion of employment-related trends and issues in our industry, including but not limited to the effects of the COVID-19 pandemic.»
🔗 Заполнить Documentation Salary Survey 2021
❤1
О том как быть более лучшим и добрым редактором.
Open Strategy Partners рассказывают и показывают на своем примере что такое Позитивный Подход при вычитке чужих работ.
Кроме самого посыла про более добрый и аккуратный подход к редактуре чужих текстов статья полна другими годными ссылками, например на внутренние Руководства по редактированию и видео про внутренние процессы редактуры.
🔗 Читать: The Positivity Pass and Why We Do It: Empathetic and constructive editing produces consistently better results and relationships over time.
#voicetone #en #resource
Open Strategy Partners рассказывают и показывают на своем примере что такое Позитивный Подход при вычитке чужих работ.
Кроме самого посыла про более добрый и аккуратный подход к редактуре чужих текстов статья полна другими годными ссылками, например на внутренние Руководства по редактированию и видео про внутренние процессы редактуры.
🔗 Читать: The Positivity Pass and Why We Do It: Empathetic and constructive editing produces consistently better results and relationships over time.
#voicetone #en #resource
❤1
Выходим из недельного застоя:
1. Статья о шести характеристиках хорошей докментации. Тут без откровений. Характеристик хорошей документации куда больше, но помнить об основе — надо
🔗Читать: Six characteristics of good docs
2. Если вы любитель «second brain» приложений а-ля Notion, есть большая вероятность, что вы уже открыли для себя Obsidian, про который я когда-то уже пару раз писал. Из подписчиков точно кто-то пользовался в компании. Так вот, для него вышел плашин с лучшим линтером простого, челвоеческого английского — Vale. Есть поддержка как и платной серверной версии, так и бесплатной CLI.
🔗 Читать: New plugin: Obsidian Vale
3. Из личного опыта. Писал тут когда-то про Mark — утилиту для синхронизации .md файлов с Clonfluence, которую можно запрячь в CI и вот это вот всё. Пост вызвал относительно бурную дискуссию и в том числе упрёки, что ничего там не работает. Добрался я таки до этой тулзы сам и имею сказать, что все работает. Пользоваться рекомендую Докер-образом и в качестве пароля передавать API-токен. Работает даже на Маке.
#ide #knowledgemanagement #en #testthedocs
1. Статья о шести характеристиках хорошей докментации. Тут без откровений. Характеристик хорошей документации куда больше, но помнить об основе — надо
🔗Читать: Six characteristics of good docs
2. Если вы любитель «second brain» приложений а-ля Notion, есть большая вероятность, что вы уже открыли для себя Obsidian, про который я когда-то уже пару раз писал. Из подписчиков точно кто-то пользовался в компании. Так вот, для него вышел плашин с лучшим линтером простого, челвоеческого английского — Vale. Есть поддержка как и платной серверной версии, так и бесплатной CLI.
🔗 Читать: New plugin: Obsidian Vale
3. Из личного опыта. Писал тут когда-то про Mark — утилиту для синхронизации .md файлов с Clonfluence, которую можно запрячь в CI и вот это вот всё. Пост вызвал относительно бурную дискуссию и в том числе упрёки, что ничего там не работает. Добрался я таки до этой тулзы сам и имею сказать, что все работает. Пользоваться рекомендую Докер-образом и в качестве пароля передавать API-токен. Работает даже на Маке.
#ide #knowledgemanagement #en #testthedocs
❤1