Как обычно, многое из технической документации годится и для авторов блогов и прочего контента для разработчиков. Конспект выступления на PyCon US 2022 “Как писать документацию, которая нравится разработчикам”

1)Сразу к делу - вычеркивайте лирику и начинайте с реальных проблема. Все равно все до этого момента проскролят;
2)Проматывание - это вообще нормальный способ чтения документации, сделайте так, чтобы скролилось удобно: заголовки, подзаголовки, названия библиотек жирным и т.п.
3)Проверяйте (и лучше в другом окружении, а не на себе), если документации нет, ее можно поискать в другом месте, если она с ошибками, вы крадете время у разработчиков;
4)Не рассказывайте, а показывайте, что делает ваш продукт
5)Инклюзивно и читабельно - избавляйтесь от оценочных словечек вроде “просто” - для кого-то предложенное может быть очень даже непросто. Используйте меньше академичных словечек и не забывайте, что не у всех такой же опыт, как у вас. “Пишите так, как говорят ваши пользователи”. Лучше не использовать локальных культурных отсылок, которые будут не знакомы пользователям вне вашего культурного контекста.
6)Меньше аббревиатур - их в IT столько, что уже некоторые имеют несколько значений
7)Не стесняйтесь приложить к документации глоссарий - как результат вышеперечисленного, уместно будет дать возможность проверить, что вы имеете в виду одно и то же, используя какие-то термины. #инструменты #конспект