Jump to content
Калькуляторы

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

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

 

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

 

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

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

 

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

Share this post


Link to post
Share on other sites

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

 

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

 

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

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

 

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

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

Share this post


Link to post
Share on other sites

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

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

 

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

 

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

 

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

 

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

Share this post


Link to post
Share on other sites

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

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

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

Share this post


Link to post
Share on other sites

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

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

 

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

Share this post


Link to post
Share on other sites

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

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

Share this post


Link to post
Share on other sites

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

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

 

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

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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

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

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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

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

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

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

Share this post


Link to post
Share on other sites

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

 

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

Share this post


Link to post
Share on other sites

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

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

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

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

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

Share this post


Link to post
Share on other sites

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

 

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

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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

 

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

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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

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

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

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

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

 

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

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

 

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

 

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

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
Sign in to follow this