*хруст пальцами*
Ну штош, приступим.
📃 Сегодня у нас небольшая подборочка накопившегося.
💥 1. Неплохой гайд под названием “The Insider’s Guide to Becoming a (Contract) Technical Writer” от автора (вроде как) хорошего курса для техписов becometechnicalwriter.com. В гайде автор проходится по всей базе того, что необходимо для контрактной работы техписателем. Гайд больше для жителей US, но большáя часть информации довольно общая, поэтому можно взглянуть одним глазком. Про всё, начиная с резюме, заканчивая наставлениями как не унывать, когда тебя морозят или пытаются нагрузить куда более большим объемом работы, чем было обговоренно зараннее.
🔗 Читать: “The Insider’s Guide to Becoming a (Contract) Technical Writer”
💥 2. Небольшой очерк на извечную тему “почему все так плохо с документацией и что с этим делать” под названием “Software makers have gotten worse at documentation and here's why that's a problem”. Никаких откровений после прочтения не будет, но напомнить себе о нашей с вами полезности лишним не будет.
🔗 Читать: “Software makers have gotten worse at documentation and here's why that's a problem”
💥 3. Заметка “Why programmers don’t write documentation” на очевидную тему но с парочкой довольно годных пойнтов (кроме того, что как бы ну.. должны писать доку мы, а не девелоперы). Заметка была ответом на совсем уж дурацкую статью “This Is Why Most Software Engineers Don’t Write Documentation”, где основным пойнтом было то, что мол нет годных тулз для документирования 🤷
🔗 Читать:“Why programmers don’t write documentation”
💥 4. Гигантский наброс от ко-фаундера и организатора Write The Docs под провокационным названием “Documentation Considered Harmful”. Весь пост проходит под слоганом “documentation may in fact be more harmful than it is helpful”. Ругается на сложность языков и оверусложненные продукты. Самый интересный материал из подборки.
🔗 Читать: “Documentation Considered Harmful”.
#career #en #article
Ну штош, приступим.
📃 Сегодня у нас небольшая подборочка накопившегося.
💥 1. Неплохой гайд под названием “The Insider’s Guide to Becoming a (Contract) Technical Writer” от автора (вроде как) хорошего курса для техписов becometechnicalwriter.com. В гайде автор проходится по всей базе того, что необходимо для контрактной работы техписателем. Гайд больше для жителей US, но большáя часть информации довольно общая, поэтому можно взглянуть одним глазком. Про всё, начиная с резюме, заканчивая наставлениями как не унывать, когда тебя морозят или пытаются нагрузить куда более большим объемом работы, чем было обговоренно зараннее.
🔗 Читать: “The Insider’s Guide to Becoming a (Contract) Technical Writer”
💥 2. Небольшой очерк на извечную тему “почему все так плохо с документацией и что с этим делать” под названием “Software makers have gotten worse at documentation and here's why that's a problem”. Никаких откровений после прочтения не будет, но напомнить себе о нашей с вами полезности лишним не будет.
🔗 Читать: “Software makers have gotten worse at documentation and here's why that's a problem”
💥 3. Заметка “Why programmers don’t write documentation” на очевидную тему но с парочкой довольно годных пойнтов (кроме того, что как бы ну.. должны писать доку мы, а не девелоперы). Заметка была ответом на совсем уж дурацкую статью “This Is Why Most Software Engineers Don’t Write Documentation”, где основным пойнтом было то, что мол нет годных тулз для документирования 🤷
🔗 Читать:“Why programmers don’t write documentation”
💥 4. Гигантский наброс от ко-фаундера и организатора Write The Docs под провокационным названием “Documentation Considered Harmful”. Весь пост проходит под слоганом “documentation may in fact be more harmful than it is helpful”. Ругается на сложность языков и оверусложненные продукты. Самый интересный материал из подборки.
🔗 Читать: “Documentation Considered Harmful”.
#career #en #article
❤1
Клёвый взгляд изнутри на то, как GitHub менеджит свои доки с помошью своих же Actions. Можно чего-нить подсмотреть и стырить себе или просто ознакомиться с концепцией Экшнсов.
Вот бы все большие компании были так же открыты как гитхабыч, приятно смотреть же!
🔗 Читать: How we use GitHub Actions to manage GitHub Docs
#example #knowledgemanagement
Вот бы все большие компании были так же открыты как гитхабыч, приятно смотреть же!
🔗 Читать: How we use GitHub Actions to manage GitHub Docs
#example #knowledgemanagement
❤1
Интересный взгляд на проблему хаоса и устаревания информации в сфере ноледж шейринга через призму энтропии.
Автор предлагает стремиться нe к утопическому “идеально”, так как это априори недостижимо, а скорее к более реальному “достаточно хорошо”. Распознание мест и моментов, когда крошечная доза порядка сейчас принесет долговременные профиты — вот путь к успеху по мнению автора.
🔗 Читать: Entropy and knowledge management
#knowledgemanagement #en #article
Автор предлагает стремиться нe к утопическому “идеально”, так как это априори недостижимо, а скорее к более реальному “достаточно хорошо”. Распознание мест и моментов, когда крошечная доза порядка сейчас принесет долговременные профиты — вот путь к успеху по мнению автора.
🔗 Читать: Entropy and knowledge management
#knowledgemanagement #en #article
❤1
Docusaurus 2 вышел из стадии альфы!
С объявлением о бета-версии команда еще больше уверена, что Docusaurus 2 готов к массовому внедрению!
Авторы гордо предлагают ознакомиться с галереей уже готовых сайтов на второй версии cтатик-сайто-генератора.
Что до целей беты - можно прочитать в самом анонсе.
#tool #en
С объявлением о бета-версии команда еще больше уверена, что Docusaurus 2 готов к массовому внедрению!
Авторы гордо предлагают ознакомиться с галереей уже готовых сайтов на второй версии cтатик-сайто-генератора.
Что до целей беты - можно прочитать в самом анонсе.
#tool #en
❤1
👀 На просторах ЛинкедИна набрел на отличный пост Daria Shatsylo про то, почему из команды уходят техписы. ИМХО, довольно реалистичный взгляд на вещи. Как четко подметили в комментариях, можно смело брать статью и кидать своим ПМ’ам.
Предисловие:
Наличие технического писателя в команде воспринимается либо как нечто само собой разумеющееся, либо как нечто вызывающее вопросы “Ты кто? Ты что тут делаешь?”.
Но когда технический писатель уходит из команды, его отсутствие можно сравнить с отсутствием маленького кусочка в большом и сложном паззле. Без этого кусочка можно обойтись. Но внимательный наблюдатель заметит, что картина команда не полная, в ней явно кого-то не хватает.
А именно не хватает человека, который охотно и каждый день берет на себя всю эту писанину. А без нее никак на проекте.
Почему же такой человек в один прекрасный день может взять и уйти?
🔗 Читать: Почему из команды уходит техписатель? У меня на это 5 причин
Бонус-P.S:
🔗 Читать: 14 Ways to Make a Good Technical Writer Quit
#career #ru
Предисловие:
Наличие технического писателя в команде воспринимается либо как нечто само собой разумеющееся, либо как нечто вызывающее вопросы “Ты кто? Ты что тут делаешь?”.
Но когда технический писатель уходит из команды, его отсутствие можно сравнить с отсутствием маленького кусочка в большом и сложном паззле. Без этого кусочка можно обойтись. Но внимательный наблюдатель заметит, что картина команда не полная, в ней явно кого-то не хватает.
А именно не хватает человека, который охотно и каждый день берет на себя всю эту писанину. А без нее никак на проекте.
Почему же такой человек в один прекрасный день может взять и уйти?
🔗 Читать: Почему из команды уходит техписатель? У меня на это 5 причин
Бонус-P.S:
🔗 Читать: 14 Ways to Make a Good Technical Writer Quit
#career #ru
❤1
В Google Docs готовится что-то крутое
https://twitter.com/GoogleWorkspace/status/1394703393600544771?s=19
#tool #en
https://twitter.com/GoogleWorkspace/status/1394703393600544771?s=19
#tool #en
Twitter
Google Workspace
Introducing smart canvas—a new product experience that transforms collaboration in #GoogleWorkspace. Learn about the new ways to collaborate in #GoogleDocs, #GoogleSheets, #GoogleSlides, and more → goo.gle/2QqRgHr #GoogleIO
❤1
Всем привет!
Иксолла открыла прием заявок на направление 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..накопилось много годноты.