Comments 13
Особенно "доставляет", когда через пот и слезы находишь ошибки в документации, которой много лет и которой пользуются буквально миллионы. С год назад была такая по формату одного из конфигурационных файлов у питона/анаконды. Искать лениво, но почему-то уверен, что она всё ещё там.
Бывает, бывает. Если такое в коде, то говорит о том, что читатели либо не пользуются данным функционалом, либо достаточно квалифицированны, чтобы исправить, как надо, на своей стороне, и слишком ленивы, чтобы заявить баг.
А я стараюсь багрепортить, даже когда лень. Вот пример
Меня всегда бесило отсутствие примеров, как это все готовить. В этом плане документации по Vue.js выше всяких похвал. Она бесподобна. Но есть нехорошие сервисы, которые дают набор классов и как бы догадывайся сам, что с ними делать.
Есть такое слово — dogfooding...
Давайте разберём пять основных претензий читателей к технической документации, и подумаем, что со всем этим делать.
Вы пишете документацию не для того чтобы она была понятна и полезна пользователям, а так чтобы она была понятна вашим программистам, полезна вашим маркетологам для рекламы модных фич, и нравилась вашему начальству.
0- у документации нет бизнес вэлью.
Чётко указывать атрибуты актуальности каждого блока информации.
А кто это будет актуализировать? Видел в одной конторе с тысячами сотрудников корпоративный Конфлуенс. Люди сотнями приходят и уходят. Новые пытаются разобраться что актуально а что нет, делают новые страницы, шарят их с коллегами, уходят. Поиск бесполезен, результаты исчисляются сотнями. И так снова и снова, и дела никому нет, шары как бы ничейные, удалять или нет, непонятно, вдруг там важное.
В общем, решили делать страницы в личных спейсах, а шарить только ссылки на них. Как только человек уходит, его страницы с аккаунтом помечаются как неактивные. И либо коллега подбирает их себе на поддержку в свой спейс, либо в мусор.
Лички в конфлю зло ) Я наблюдаю ситуацию когда тащат в лички с общих ресурсов, там что-то дорабатывают и потом коллеги в поиске получают десяток дублей одной статьи. При этом не понятно, что из этого можно применять. Думаю только модерация может спасти ситуацию, но обычно это бросают на самотек и ждут пока конфлю не станет болотом (
Кстати, а есть ведь ещё вариант "не плодить фичи ради фич", по идее должно помочь и с распуханием доков и с актуализацией.
Почему пользователи ненавидят вашу документацию и как это исправить