💰 Подъехали результаты опроса по зарплатам Техписателей за 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
JetBrains запостили у себя статью, которая у меня была отложена на поделиться с вами попозже, так что here we go!
В статье автор усиленно сетует на стагнацию техрайт тулинга, на отсутствие каких-либо стандартов (да, десятки сортов markdown, asciidoc, DITA и прочие, это мы про вас), отсутствие версионности, предназначенной для документации и всякое такое (статья хорошая, советую прочесть, проникнитесь может)
Но больше всего из этого интересен тред самих JetBrains, где они рассуждают, что стандарт упрощенного языка разметки нужен, и он как раз должен быть таким, каким описал его автор статьи.
🤔 К чему пришли в JetBrains в своей новой IDE для Техписов:
>What we’ve come up with for ourselves is a semantic XML-based markup with smart completion along with Markdown support. And you can mix the two in any proportion to stay light and still inject more complex markup if you need extra features like tabs or advanced code blocks.
🔗 Читать: Better docs, less pain: the case for new docs-as-code standards
#ide #en #markdown #article
В статье автор усиленно сетует на стагнацию техрайт тулинга, на отсутствие каких-либо стандартов (да, десятки сортов markdown, asciidoc, DITA и прочие, это мы про вас), отсутствие версионности, предназначенной для документации и всякое такое (статья хорошая, советую прочесть, проникнитесь может)
Но больше всего из этого интересен тред самих JetBrains, где они рассуждают, что стандарт упрощенного языка разметки нужен, и он как раз должен быть таким, каким описал его автор статьи.
🤔 К чему пришли в JetBrains в своей новой IDE для Техписов:
>What we’ve come up with for ourselves is a semantic XML-based markup with smart completion along with Markdown support. And you can mix the two in any proportion to stay light and still inject more complex markup if you need extra features like tabs or advanced code blocks.
🔗 Читать: Better docs, less pain: the case for new docs-as-code standards
#ide #en #markdown #article
❤1
# Code needs documentation to become a project
🐙 GitHub выкатила красивейший data-driven (простите) отчет о своей деятельности за 2021 год: The 2021 State of the Octoverse. Там вам и графики, и статистика пользователей, и самые популярные языки.
Отчет разделен на 4 части, Overview, что-то для программистов, про поддержку коммьюнити и 🥁документация!🥁! Нас особенно интересует конечно же последнее.
Раздел про документацию полон интересной статистической информации и выводов из нее. Особенно понравился раздел о том, что "GitHub Issues are documentation too" и сразу же за ним совет создать Good First Issues guide.
Однозначно материал месяца, обязательно к ознакомлению
🔗 Читать: Creating documentation to support developers
#article #en
🐙 GitHub выкатила красивейший data-driven (простите) отчет о своей деятельности за 2021 год: The 2021 State of the Octoverse. Там вам и графики, и статистика пользователей, и самые популярные языки.
Отчет разделен на 4 части, Overview, что-то для программистов, про поддержку коммьюнити и 🥁документация!🥁! Нас особенно интересует конечно же последнее.
Раздел про документацию полон интересной статистической информации и выводов из нее. Особенно понравился раздел о том, что "GitHub Issues are documentation too" и сразу же за ним совет создать Good First Issues guide.
Однозначно материал месяца, обязательно к ознакомлению
🔗 Читать: Creating documentation to support developers
#article #en
❤1