Я некогда писал об Obsidian. Это такая "база знаний", но без "облачных" примочек, живёт это дело поверх локальной папочки с .md файликами. Можно смотреть связи и всякое такое.

Недавно на глаза попалось нечто похожее под названием Foam. На этот раз всё обёрнуто в vscode и приправлено довольно популярными расширениями. Автор предупреждает, что пока всё готово примерно на ~10%. Можно залайкать и следить за релизами, авось чего и вырастет из этого

#ide #knowledgemanagement #tool #markdown

Познавательная "behind-the-scenes "-статейка от GitHub о том как они перезапускали docs.github.com и с какими проблемами сталкивались и как их решали.

https://github.blog/2020-07-02-how-we-launched-docs-github-com/

#article #markdown #DocsAsCode

В далёком 2016 Airbnb поделились своей болью со скейлингом шаринга (простите) знаний и вариантами того, как это дело обуздать. В статье без откровений, но мне она нравится, подойдет как старт для тех, кто только задумался о построении системы по обмену знаниями внутри компании/команды.

И все эти годы они спокойно себе пилили свой 🚲. Судя по чейнджлогам - выглядит интересно. Делюсь, может кому подойдет.

Документация по этой системе живет тут

#knowledgemanagement #article #en #changelog #example

Набрёл на DocForge – утилиту (пре-пуш тула) которая отслеживает, не устарели ли куски кода в документации. Никакой сложной настройки, пример конфигурации на скрине выше. Насколько я понял, в данный момент всё это дело еще не доступно, но товарищи просят к ним постучаться и предлагают попользовать их свежеиспеченную разработку или забукать демо.

#tool #en #DocsAsCode

У меня сейчас проходит небольшой цикл ревью очень маленьких кусочков текста (те самые microcopy) которые я писал довольно давно. И имею сказать, что усилия, требуемые, чтобы получилось ХОРОШО несоизмеримо выше усилий, которые нужно приложить, чтобы писать обычную (конечно же читабельную) документацию.

Очень согласен с этим твитом, can relate, так сказать:

https://twitter.com/krnswry/status/1283075386495074307

#resource #en #language

Дано: посудомойка с 5 режимами.

Необходимо: понять что делает второй пункт.

#example #en #visual

Вывод: опозориться можно и в документации, состоящей из одного слова и одной картинки. Иногда (при неумении/неопытности - всегда) лучше не креативить, а писать как есть. Только узнав и научившись как делать нужно, можно начать делать так, как хочется и гнуть (ну ладно, more like подгибать) правила под себя.

Hint: чтобы посмотреть правильный ответ, нажмите на 💡

#example

Я очень люблю узнавать о чужих процессах и читать о том как их строят и вообще о внутренней кухне. Недавно подвернулся сайтец Greater Greater Washington, на котором чуваки на волонтёрской основе топят за все хорошее и против всего плохого в своем округе, улучшают район и всячески его развивают.

Кроме оффлайн активностей, товарищи ведут активный блог и ведут его основательно, у них даже есть свой стайлгайд, и они даже его опубликовали. Да, он не технический, но полезно и интересно посмотреть на чужую работу.

Есть даже отдельная статья в бложике, где они уведомляют об обновлении стайлгайда и подробно расписывают почему было сделано то или иное изменение.

Это пример отличной коммуникации и knowledge sharing attitude, будьте как Greater Greater Washington!

#example #career #en

ReadMe (которые personalized, interactive developer hubs) ведут офигенский documentation-related блог, рекомендую!

Сегодня попалась на глаза их обширная статья о том как начать вкатываться в Swagger + OpenAPI документацию. Темплейты, бест поактисы, тулзы и примеры. Всё к вашим услугам! Нормально подойдет для базовых познаний что там да как.

Бонус трек - Mockoon, мокалка API, которая умеет всё локально (No remote deployment, no account required, open source.), еще и кроссплатформенная.

#API #example #resource #article #en

К вопросу о том как выпрыгнуть из цикла Нужна работа --> Для работы нужен опыт --> Для опыта нужна работа. Получить хоть какое-то портфолио для начала карьеры в техписательстве или просто помочь сообществу если есть пара свободных часов в день вполне реально.

Пару лет назад я публиковал пост с реддита, где можно было нажать на понравившийся или просто интересующий проект и начать туда контрибьютить. Так вот, пост обновился несколько месяцев назад и все проекты актуальны и готовы принимать ваши контрибьюшны!

Пост оч грамотно структурирован, а что главное - есть ссылка на "How to Contribute to Open Source for first-timers and for veterans."

#vacancy #career #en

Очень (очень!) хорошая статья от Nuclino о том, почему никто не читает документацию, почему это нормально и варианты разрешения этой ситуации. Nuclino сами занимаются разботкой софта для Обмена Знаниями, такой себе аналог Notion, поэтому они знают о чем говорят.

Статья написана просто прекрасно, еще и без запихивания рекламы своего продукта глубоко всем нам в горло.

Ключевые моментики из статьи:

- Никто не читает документацию и это ОК
- Документация нужна не чтобы её читать, а чтобы с ней консультироваться
- Не пишите документацию, только ради написания. Никому не нужен огромный, толстый, пускай и всеобъемлющий кусок текста
- Пишите документацию держа в голове то, что скорее всего, её будут искать в поиске, а не просматривать все оглавления
- Пишите небольшие кусочки документации и пользуйтесь кросс-ссылками, ссылаясь на другие, такие же небольшие кусочки док.

Бонусный трек: их же статья про ценность документации и сколько может стоить отказ от обмена знаниями.

#article #en #resource

Небольшая подборочка технических и стайлгайдов и парочка сопоствующих статей. Скорее всего вы про все из них слышали, возможно какие-то даже читали, но полная подборка не помешает:

- Microsoft Writing Style Guide
- Google Developer Documentation Style Guide
- Apple Style Guide
- DigitalOcean Product Documentation Style Guide
- GitHub Style Guide
- GitLab Docs Documentation Style Guide
- Mailchimp Content Style Guide
- RedHat Style Guide
- Rackspace Style Guide for Technical Content
- Splunk Style Guide

Другие полезные стайлгайды:

- Federal plain language guidelines (USA)
- IEEE Editorial Style Manual for Authors
- IBM developerWorks editorial style guide
- Online Writing Lab (OWL) at Purdue University
- Paramedic Method: A Lesson in Writing Concisely
- University of Oxford Style Guide
- The Diversity Style Guide
- Progressive’s Style Guide

#styleguide #en

Тут наше любимое! Статейка чтоб была под рукой в следующий спор

Функционал или функциональность 

Пишете про технологии, стартапы и приложения — статья точно поможет поставить жирную точку в этом споре:
 
https://nepishi.ru/s/function/

Залежалась в закладках статья (статья старая, кидал вам её сюда еще в 2018, а перевод свежий 🇷🇺) про UX Writing от Гугла.

Статья особенно полезна примерами как делать и как не.

Там и про бренд войс и про тон и, собственно, очень полезный чеклист, чтобы ничего не упустить! Если не осилили её на английском, крайне советую прочитать сейчас

#uiux #ru #en #article

Пишите понятную документацию, рисуйте её значками и символами если нужно, упрощайте, и делайте всё для людей, но будто для детей, чтобы небыло вот так:

https://twitter.com/jaredpalmer/status/1293537083399839744?s=20

Всем хорошей пятницы и приятных выходных

#example

Пост заслуживает внимания! Это очень крутой учебник!

#knowledgemanagement #ru #book

↓↓↓↓↓↓↓↓

Управления знаниями пост

Автор канала с коллегами потратил больше полугода своей жизни на то, чтобы сделать внятный учебник по управлению знаниями и, похоже, пришло время презентовать его общественности.

Мы хотим сделать хорошую, структурированную базу знаний, которая поможет вам и вашим IT-компаниям систематически поправить онбординг, внедрить фиксацию и обмен знаниями, сформировать профессиональные сообщества и разрушить стены между людьми и командами.
И, конечно, мы много внимания хотим уделить вещам, которые дают эффект сразу.

Далеко не всё ещё оформлено, у нас огромный бэклог с полезным контентом, но уже сейчас можно посвятить время изучению гайда, поделиться с коллегами и положить сайт в закладки.