Джулия Эванс, регулярный гость в нашем уютном бложике, но на этот раз не с своими прекрасными Зинами Для Программистов, а с перечнем так-себе-паттернов затрудняющих восприятие информации и кайфовые примеры к ним.
💥паттерн 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
This media is not supported in your browser
VIEW IN TELEGRAM
❓ Не совсем по теме документации, но обнаружена офигенная аппка на мак — Fig (https://fig.io/) добавляет VSCode-лайк автокомплит всем командам в терминале.
Соответственно вопрос, стоит ли делиться годными штуками, которые не сильно и связаны с докумментацией, но косвенно помогут в ее создании?
Соответственно вопрос, стоит ли делиться годными штуками, которые не сильно и связаны с докумментацией, но косвенно помогут в ее создании?
❤2
📓 В лучший линтер для прозы Vale по просьбам трудящихся завезли улучшенные метрики читабельности.
На трудность восприятия текста могут оказывать влияние следующие лингвистические особенности:
- длина слов и предложений,
- сложность синтаксических конструкций (наличие однородных членов предложения и предложно-падежных групп, перегруженность причастными и деепричастными оборотами),
- показатели частотности слова,
- уровень абстрактности лексики,
- обилие терминов
Эти метрики пусть и не сильно, но позволяют оптимизировать свои тексты. Следить за длиной предложений и их сложностью больше не нужно, теперь это можно поручить алгоритму.
Среди новых метрик:
- Automated readability index (ARI)
- Coleman–Liau
- Flesch–Kincaid
- Flesch reading ease
- Gunning fog
- LIX
- SMOG
🔗 Скачать: Vale-compatible implementations of many popular "readability" metrics
#testthedocs #en #tool
На трудность восприятия текста могут оказывать влияние следующие лингвистические особенности:
- длина слов и предложений,
- сложность синтаксических конструкций (наличие однородных членов предложения и предложно-падежных групп, перегруженность причастными и деепричастными оборотами),
- показатели частотности слова,
- уровень абстрактности лексики,
- обилие терминов
Эти метрики пусть и не сильно, но позволяют оптимизировать свои тексты. Следить за длиной предложений и их сложностью больше не нужно, теперь это можно поручить алгоритму.
Среди новых метрик:
- Automated readability index (ARI)
- Coleman–Liau
- Flesch–Kincaid
- Flesch reading ease
- Gunning fog
- LIX
- SMOG
🔗 Скачать: Vale-compatible implementations of many popular "readability" metrics
#testthedocs #en #tool
❤1
👀 Интересный взгляд на Season of Docs 2021 изнутри.
Redocly (генератор Swagger-API-доки) рассказали как прошло их участие в Google Season of Docs.
Если вы хотите принять участие как контрибьютор или ваша организация хочет подать своей проект на участие, или же вам просто интересно как устроены такие ивенты изнутри — статья для вас.
Очень приятная открытость изложения, рассказали даже о таких щепетильных моментиках как бюджетирование. Структура статьие четкая и ясная, вот такая была проблема, вот решили делать то-то, а успех планируем замерять вот так.
Можно поглазеть на созданные PRы, ознакомиться с таймлайном, чтобы примерно понять сколько что займет времени и наконец-то задуматься об участии в следующем году!
🔗 Читать: Redocly - Season of Docs 2021: Case study
#en #article
Redocly (генератор Swagger-API-доки) рассказали как прошло их участие в Google Season of Docs.
Если вы хотите принять участие как контрибьютор или ваша организация хочет подать своей проект на участие, или же вам просто интересно как устроены такие ивенты изнутри — статья для вас.
Очень приятная открытость изложения, рассказали даже о таких щепетильных моментиках как бюджетирование. Структура статьие четкая и ясная, вот такая была проблема, вот решили делать то-то, а успех планируем замерять вот так.
Можно поглазеть на созданные PRы, ознакомиться с таймлайном, чтобы примерно понять сколько что займет времени и наконец-то задуматься об участии в следующем году!
🔗 Читать: Redocly - Season of Docs 2021: Case study
#en #article
❤1👍1
Обновилось годное дополнение для Google Docs: Docs to Markdown.
Как можно понять из названия, позволяет в пару взмахов пальцами конвертировать вашу гугл-доку в HTML или Markdown без особой головоморочки.
Обновление минорное, добавили возможность убрать пугающие красные ворнинги, но может кто не знал о плагинчике.
#markdown #tool #en
Как можно понять из названия, позволяет в пару взмахов пальцами конвертировать вашу гугл-доку в HTML или Markdown без особой головоморочки.
Обновление минорное, добавили возможность убрать пугающие красные ворнинги, но может кто не знал о плагинчике.
#markdown #tool #en
👍1
Forwarded from Shut up and write (Shut_up_and_write_bot)
Docs for Developers
Обзор на книгу Docs for Developers: An Engineer’s Field Guide to Technical Writing, которая вышла в сентябре 2021. В посте есть спойлеры, если хотите сохранить интригу не читайте этот пост.
Книга написана в соавторстве техническими писателями из Google, Microsoft, Stripe и Monzo.
Авторы говорят, что:
Что зашло
- Легко и быстро читается.
- Книга построена как хорошая документация, не обязательно читать ее всю, если есть пробелы в какой-то конкретной теме, например, вы не знаете как оценить качество документации, то можно прочитать только одну главу. Хотя авторы рекомендуют читать книгу по порядку 😉
- Из книги можно собрать коллекцию цитат про важность документации и правильные подходы. Тезисы подтверждены ссылками на научные статьи. Я нашла статьи, которые раньше не читала.
- Есть список необходимых инструментов, чтобы написать и опубликовать первую документацию (Hugo, Vale, Netlify).
Не зашло
- Я не люблю рассказы внутри обучающих книг, а тут был рассказ про стартап, который не документировал свой API, а потом им нужно было обучить первого клиента и они ой как пожалели. Пример мне показался слишком далеким от реальности. Я эти части пропускала, чем закончилась история не знаю.
- Я ожидала прочитать реальные истории из опыта авторов, про подходы к документации в их компаниях и много практики. Этого в книге нет.
Однако
Книга мне понравилась. Но перечитывать и держать ее под рукой я не буду.
Книга подойдет всем начинающим техническим писателям. Потому что в ней не только про документацию для разработчиков. В книге есть много базовых вещей: что нужно определить аудиторию вашей документации и писать для нее; что документацию сканируют, а не читают; что писать нужно коротко, текст делить на блоки. Эти принципы правдивы для любой документации.
Если вы технический писатель с опытом, то бросать все и начинать читать книгу не надо.
Я не верю, что много разработчиков или менеджеров прочитает ее, особенно кто-то из стартапа, ведь это 200 страниц.
#developerexperience
Обзор на книгу Docs for Developers: An Engineer’s Field Guide to Technical Writing, которая вышла в сентябре 2021. В посте есть спойлеры, если хотите сохранить интригу не читайте этот пост.
Книга написана в соавторстве техническими писателями из Google, Microsoft, Stripe и Monzo.
Авторы говорят, что:
Книга разработана как ресурс, который нужно держать под рукой, чтобы вы могли включить написание документацию в процесс разработки. Эта книга поможет вам создать документацию с нуля. ©Еще обсуждение книги с авторами можно послушать в подкасте Write the Docs.
Что зашло
- Легко и быстро читается.
- Книга построена как хорошая документация, не обязательно читать ее всю, если есть пробелы в какой-то конкретной теме, например, вы не знаете как оценить качество документации, то можно прочитать только одну главу. Хотя авторы рекомендуют читать книгу по порядку 😉
- Из книги можно собрать коллекцию цитат про важность документации и правильные подходы. Тезисы подтверждены ссылками на научные статьи. Я нашла статьи, которые раньше не читала.
- Есть список необходимых инструментов, чтобы написать и опубликовать первую документацию (Hugo, Vale, Netlify).
Не зашло
- Я не люблю рассказы внутри обучающих книг, а тут был рассказ про стартап, который не документировал свой API, а потом им нужно было обучить первого клиента и они ой как пожалели. Пример мне показался слишком далеким от реальности. Я эти части пропускала, чем закончилась история не знаю.
- Я ожидала прочитать реальные истории из опыта авторов, про подходы к документации в их компаниях и много практики. Этого в книге нет.
Однако
Книга мне понравилась. Но перечитывать и держать ее под рукой я не буду.
Книга подойдет всем начинающим техническим писателям. Потому что в ней не только про документацию для разработчиков. В книге есть много базовых вещей: что нужно определить аудиторию вашей документации и писать для нее; что документацию сканируют, а не читают; что писать нужно коротко, текст делить на блоки. Эти принципы правдивы для любой документации.
Если вы технический писатель с опытом, то бросать все и начинать читать книгу не надо.
Я не верю, что много разработчиков или менеджеров прочитает ее, особенно кто-то из стартапа, ведь это 200 страниц.
#developerexperience
Docs for Developers
Documentation for Everyone
👍4
Информативный пост написанный по мотивам Knowledge Conf-доклада Семёна Факторовича, руководителя documentat.io о чувстве «бесполезности» документации (и не только).
>Чаще всего за словом «бесполезна» кроется ощущение, что документация не очень хорошо выполняет свою задачу. Потому что она либо не полна, то есть описывает не все аспекты, которые хотелось бы в ней найти. Либо не точна, то есть то, что в ней написано, не полностью соответствует истине. Либо не актуальна, то есть соответствовала истине в прошлом, а сейчас программная система или внешний мир изменились, и документация перестала этому соответствовать.
Эти проблемы и обсуждаются в этой статье. Семен предлагает взглянуть на вышеуказанные симптомы, как их интерпретировать, а самое главное — что с ними делать.
❗️Наша редакция уважает Семёна и рекомендует статью к прочтению.
🔗 Читать: Вам кажется, что с вашей документацией что-то не так? Вам не кажется
#article #ru
>Чаще всего за словом «бесполезна» кроется ощущение, что документация не очень хорошо выполняет свою задачу. Потому что она либо не полна, то есть описывает не все аспекты, которые хотелось бы в ней найти. Либо не точна, то есть то, что в ней написано, не полностью соответствует истине. Либо не актуальна, то есть соответствовала истине в прошлом, а сейчас программная система или внешний мир изменились, и документация перестала этому соответствовать.
Эти проблемы и обсуждаются в этой статье. Семен предлагает взглянуть на вышеуказанные симптомы, как их интерпретировать, а самое главное — что с ними делать.
❗️Наша редакция уважает Семёна и рекомендует статью к прочтению.
🔗 Читать: Вам кажется, что с вашей документацией что-то не так? Вам не кажется
#article #ru
Хабр
Вам кажется, что с вашей документацией что-то не так? Вам не кажется
Меня зовут Семён Факторович, с 2012 года я занимаюсь технической документацией. Последние три года я руковожу собственным агентством documentat.io , помогая российским IT-компаниям создавать...
❤1👍1🤯1