Перейти к содержимому
Калькуляторы

Как валидировать документацию? как проверять, что она понятна?

Коллеги, подскажите, как проверять понятность документации?

 

Когда мы, программисты, пишем код, то проверить его корректность понятно как: написал тест или вручную прогнал и ок, в продакшн.

 

А с документацией ведь беда: один раз человек её прочел, остался недоволен, ему пояснили, теперь он её понимает.

Т.е. человек уже становится немного непригоден для оценки понятности или непонятности текста.

 

Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста?

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Коллеги, подскажите, как проверять понятность документации?

 

Когда мы, программисты, пишем код, то проверить его корректность понятно как: написал тест или вручную прогнал и ок, в продакшн.

 

А с документацией ведь беда: один раз человек её прочел, остался недоволен, ему пояснили, теперь он её понимает.

Т.е. человек уже становится немного непригоден для оценки понятности или непонятности текста.

 

Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста?

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

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

а саппорт на что? или речь про альфу?

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

А с документацией ведь беда: один раз человек её прочел, остался недоволен, ему пояснили, теперь он её понимает.

Т.е. человек уже становится немного непригоден для оценки понятности или непонятности текста.

 

Ну зависит от того, что за человек ... Профессиональны технические писатели пригодны хоть по двадцатому разу документацию читать.

 

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

 

Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста?

 

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

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста?

Абсолютно верно. Называется альфа- и бэта-тестированием ;-)

Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время."

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста?

Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время."

 

Во, спасибо, надо внедрить.

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время."

Но ведь эта оценка скорее самоудовлетворения. Пункты то какие: "полезна/мало/чушь полнейшая". Вот вики для публичной правки и форум для вопросов - совсем другое дело.

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время."

Но ведь эта оценка скорее самоудовлетворения. Пункты то какие: "полезна/мало/чушь полнейшая". Вот вики для публичной правки и форум для вопросов - совсем другое дело.

 

вики для публичной правки — сомнительная задача. Люди пишут туда всякую фигню, а потом мне тыкают: а у вас там написано.

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Необязательно разрешать правки в вики. Главное - формат. Параметр/группа параметров = страница. Если у параметра есть аттрибуты, которые не являются самоописательными - то таким аттрибутам своя страница или раздел на текущей странице. Wiki.mikrotik.com как пример нормального справочника такого типа, имхо.

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Необязательно разрешать правки в вики.

Наверное, править то надо разрешать, но для персональнального взаимодействия, другие видят только после модерации.

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Верное замечание, слово "публичные" я как-то не подумал написать, казалось, что и так понятно

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время."

Но ведь эта оценка скорее самоудовлетворения. Пункты то какие: "полезна/мало/чушь полнейшая". Вот вики для публичной правки и форум для вопросов - совсем другое дело.

вики для публичной правки — сомнительная задача. Люди пишут туда всякую фигню, а потом мне тыкают: а у вас там написано.

Премодерация - не, не слышал? ;-)

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Премодерация - не, не слышал? ;-)

 

беглый обзор первой страницы гугла показал, что у mediwiki нет премодерации из коробоки (и тут возможны грабли при апдейтах и прочие прелести). или я не прав? или mediawiki нынче не в тренде и есть что-то, что умеет премодерацию вики-правок?

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Премодерация - не, не слышал? ;-)

беглый обзор первой страницы гугла показал, что у mediwiki нет премодерации из коробоки (и тут возможны грабли при апдейтах и прочие прелести). или я не прав? или mediawiki нынче не в тренде и есть что-то, что умеет премодерацию вики-правок?

Погоди, я правильно понимаю, что ни про плагины, ни про экстеншины ты в принципе слышать не хочешь, а пользуешься только и исключительно тем, что дают искаропки? ;-)

Позволь тебе не поверить ;-)

Это поможет? http://stackoverflow.com/questions/4813277/mediawiki-moderation

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

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

 

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

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

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

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

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

 

Это вопрос криворучия техписателя, ответственного за документацию. Видел не одну документацию, которая из одних и тех же исходников собирается и в веб-вид а-ля Вики, и в pdf-документы. А ответственный все равно понадобится, т.к. самоорганизация почему-то получается только у замусоривания :)

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

В древние времена у меня было так. Клавишу F1 писал заказчик... Он заказывал продукт, но платить ему было невмесно, поэтому для своих он F1 и написал, получил свои деньги честно. Он честно написал своим работникам, чего и как нажимать...

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Премодерация - не, не слышал? ;-)

беглый обзор первой страницы гугла показал, что у mediwiki нет премодерации из коробоки (и тут возможны грабли при апдейтах и прочие прелести). или я не прав? или mediawiki нынче не в тренде и есть что-то, что умеет премодерацию вики-правок?

Погоди, я правильно понимаю, что ни про плагины, ни про экстеншины ты в принципе слышать не хочешь, а пользуешься только и исключительно тем, что дают искаропки? ;-)

Позволь тебе не поверить ;-)

Это поможет? http://stackoverflow.com/questions/4813277/mediawiki-moderation

 

Да, видел этот тред.

Плагины и расширения это риск. Если медиавики и загнётся, то его форкнут и продолжат пилить. Судьба плагинов может быть совсем иной, всё зависит от кол-ва пользователей этого плагина. Лично я не видел ни одной вики с премодерацией, поэтому предполагаю, что пользователей этого плагина мало. Всё что я видел - либо можно вносить правки, либо нельзя (нужно получать права на внесение изменений)

 

Если у плагина премодерации полтора пользователя по всему миру, то я бы не рискнул им пользоваться(не имея хороших навыков разработки на PHP), если там больше, чем 5 экранов кода. В итоге это может превратиться в то, что сам и станешь мейнтенером этого плагина. В принципе, если речь идёт о компании разработчике ПО, то для такой компании это не сложно.

 

Сам лично пользуюсь расширениями Adblock и Flashblock для браузеров Chromium и Firefox. Но тут нет рисков, подобных плагину премодерации для mediawiki. Тут несколько иные риски, что в эти расширения подсунут тройн (подобные случаи вроде бы даже были, только засовывали не троян, а adware)

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

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

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

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

Поделиться сообщением


Ссылка на сообщение
Поделиться на других сайтах

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Гость
Ответить в тему...

×   Вставлено в виде отформатированного текста.   Вставить в виде обычного текста

  Разрешено не более 75 смайлов.

×   Ваша ссылка была автоматически встроена.   Отобразить как ссылку

×   Ваш предыдущий контент был восстановлен.   Очистить редактор

×   Вы не можете вставить изображения напрямую. Загрузите или вставьте изображения по ссылке.