maxlapshin Опубликовано 9 января, 2015 · Жалоба Коллеги, подскажите, как проверять понятность документации? Когда мы, программисты, пишем код, то проверить его корректность понятно как: написал тест или вручную прогнал и ок, в продакшн. А с документацией ведь беда: один раз человек её прочел, остался недоволен, ему пояснили, теперь он её понимает. Т.е. человек уже становится немного непригоден для оценки понятности или непонятности текста. Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста? Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
vodz Опубликовано 9 января, 2015 · Жалоба Коллеги, подскажите, как проверять понятность документации? Когда мы, программисты, пишем код, то проверить его корректность понятно как: написал тест или вручную прогнал и ок, в продакшн. А с документацией ведь беда: один раз человек её прочел, остался недоволен, ему пояснили, теперь он её понимает. Т.е. человек уже становится немного непригоден для оценки понятности или непонятности текста. Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста? Если нет опыта и рыбы, то только так как написали: для себя - вносить всё непонятое новым человеком; для других - изменять чтобы им было понятно по их замечаниям. Надо ж понимать, что можно поискать образцы, а потом будет опыт и рыба и впоследующем уже проще. Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
SergioDeMaster Опубликовано 9 января, 2015 · Жалоба а саппорт на что? или речь про альфу? Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
dimas Опубликовано 9 января, 2015 · Жалоба А с документацией ведь беда: один раз человек её прочел, остался недоволен, ему пояснили, теперь он её понимает. Т.е. человек уже становится немного непригоден для оценки понятности или непонятности текста. Ну зависит от того, что за человек ... Профессиональны технические писатели пригодны хоть по двадцатому разу документацию читать. Если внутренняя документация по разработке или установке - можно попросить поправить того, кому непонятно, потом отдать на ревью остальным. Саппорту. Собирать фидбек пользователей, если их достаточно - вопросы будут. Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста? Ну как минимум каждую мажорную версию продукта неплохо делать полное ревью документации техписами или саппортом или внедренцами. А еще заодно делать анализ обращений в саппорт на предмет тех, что можно было бы избежать, если доработать документацию ... Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
vIv Опубликовано 9 января, 2015 · Жалоба Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста? Абсолютно верно. Называется альфа- и бэта-тестированием ;-) Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время." Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
maxlapshin Опубликовано 9 января, 2015 · Жалоба Как же разбираться с этой проблемой? Каждый раз искать нового человека, что бы он оценивал степень полезности нового текста? Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время." Во, спасибо, надо внедрить. Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
vodz Опубликовано 9 января, 2015 · Жалоба Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время." Но ведь эта оценка скорее самоудовлетворения. Пункты то какие: "полезна/мало/чушь полнейшая". Вот вики для публичной правки и форум для вопросов - совсем другое дело. Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
maxlapshin Опубликовано 10 января, 2015 · Жалоба Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время." Но ведь эта оценка скорее самоудовлетворения. Пункты то какие: "полезна/мало/чушь полнейшая". Вот вики для публичной правки и форум для вопросов - совсем другое дело. вики для публичной правки — сомнительная задача. Люди пишут туда всякую фигню, а потом мне тыкают: а у вас там написано. Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
ChargeSet Опубликовано 10 января, 2015 · Жалоба Необязательно разрешать правки в вики. Главное - формат. Параметр/группа параметров = страница. Если у параметра есть аттрибуты, которые не являются самоописательными - то таким аттрибутам своя страница или раздел на текущей странице. Wiki.mikrotik.com как пример нормального справочника такого типа, имхо. Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
vodz Опубликовано 10 января, 2015 · Жалоба Необязательно разрешать правки в вики. Наверное, править то надо разрешать, но для персональнального взаимодействия, другие видят только после модерации. Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
ChargeSet Опубликовано 10 января, 2015 · Жалоба Верное замечание, слово "публичные" я как-то не подумал написать, казалось, что и так понятно Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
vIv Опубликовано 10 января, 2015 · Жалоба Замечал на всяких сайтах и во всяких хэлпах опросники "Эта информация была вам полезна? Оцените, если есть время." Но ведь эта оценка скорее самоудовлетворения. Пункты то какие: "полезна/мало/чушь полнейшая". Вот вики для публичной правки и форум для вопросов - совсем другое дело. вики для публичной правки — сомнительная задача. Люди пишут туда всякую фигню, а потом мне тыкают: а у вас там написано. Премодерация - не, не слышал? ;-) Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
s.lobanov Опубликовано 10 января, 2015 · Жалоба Премодерация - не, не слышал? ;-) беглый обзор первой страницы гугла показал, что у mediwiki нет премодерации из коробоки (и тут возможны грабли при апдейтах и прочие прелести). или я не прав? или mediawiki нынче не в тренде и есть что-то, что умеет премодерацию вики-правок? Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
vIv Опубликовано 10 января, 2015 · Жалоба Премодерация - не, не слышал? ;-) беглый обзор первой страницы гугла показал, что у mediwiki нет премодерации из коробоки (и тут возможны грабли при апдейтах и прочие прелести). или я не прав? или mediawiki нынче не в тренде и есть что-то, что умеет премодерацию вики-правок? Погоди, я правильно понимаю, что ни про плагины, ни про экстеншины ты в принципе слышать не хочешь, а пользуешься только и исключительно тем, что дают искаропки? ;-) Позволь тебе не поверить ;-) Это поможет? http://stackoverflow.com/questions/4813277/mediawiki-moderation Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
dimas Опубликовано 10 января, 2015 · Жалоба Мне все-таки кажется что Вики для документации продукта не то ... Если очень хочется маркдаун синтаксиса - то вариантов то куча, например питоновские Сфинкс. А для обратной связи достаточно поставить какой-нить из плагинов, который даст выделить кусок документации, и отправить фидбэк производителю. А вот если хочется кроме документации вести некую базу знаний а-ля KB, на темы фиксов, воркэраундов ошибок и т.д., вплоть до выкладывания фиксов - да, что-то викоподобное может быть полезным, но там наверняка захочется разгнаничения уровня доступа, типа саппорт/альфа-тестеры/легальные клиенты/кто угодно, например ... Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
Sergey Gilfanov Опубликовано 10 января, 2015 · Жалоба У вики есть крупный недостаток. Она способствует тому, что результат нельзя читать линейно. И, соответственно, нельзя пролистать такую документацию 'по диагонали' для формирования общего представления. А специальную главу на этот счет написать - это очень трудно. Ну и написание линейного текста сильно способствует тому, что пишущий подумает, как все понятно изложить, а не просто накидать поток сознания. Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
dimas Опубликовано 10 января, 2015 · Жалоба У вики есть крупный недостаток. Она способствует тому, что результат нельзя читать линейно. И, соответственно, нельзя пролистать такую документацию 'по диагонали' для формирования общего представления. А специальную главу на этот счет написать - это очень трудно. Ну и написание линейного текста сильно способствует тому, что пишущий подумает, как все понятно изложить, а не просто накидать поток сознания. Это вопрос криворучия техписателя, ответственного за документацию. Видел не одну документацию, которая из одних и тех же исходников собирается и в веб-вид а-ля Вики, и в pdf-документы. А ответственный все равно понадобится, т.к. самоорганизация почему-то получается только у замусоривания :) Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
YuryD Опубликовано 11 января, 2015 · Жалоба В древние времена у меня было так. Клавишу F1 писал заказчик... Он заказывал продукт, но платить ему было невмесно, поэтому для своих он F1 и написал, получил свои деньги честно. Он честно написал своим работникам, чего и как нажимать... Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
s.lobanov Опубликовано 11 января, 2015 · Жалоба Премодерация - не, не слышал? ;-) беглый обзор первой страницы гугла показал, что у mediwiki нет премодерации из коробоки (и тут возможны грабли при апдейтах и прочие прелести). или я не прав? или mediawiki нынче не в тренде и есть что-то, что умеет премодерацию вики-правок? Погоди, я правильно понимаю, что ни про плагины, ни про экстеншины ты в принципе слышать не хочешь, а пользуешься только и исключительно тем, что дают искаропки? ;-) Позволь тебе не поверить ;-) Это поможет? http://stackoverflow.com/questions/4813277/mediawiki-moderation Да, видел этот тред. Плагины и расширения это риск. Если медиавики и загнётся, то его форкнут и продолжат пилить. Судьба плагинов может быть совсем иной, всё зависит от кол-ва пользователей этого плагина. Лично я не видел ни одной вики с премодерацией, поэтому предполагаю, что пользователей этого плагина мало. Всё что я видел - либо можно вносить правки, либо нельзя (нужно получать права на внесение изменений) Если у плагина премодерации полтора пользователя по всему миру, то я бы не рискнул им пользоваться(не имея хороших навыков разработки на PHP), если там больше, чем 5 экранов кода. В итоге это может превратиться в то, что сам и станешь мейнтенером этого плагина. В принципе, если речь идёт о компании разработчике ПО, то для такой компании это не сложно. Сам лично пользуюсь расширениями Adblock и Flashblock для браузеров Chromium и Firefox. Но тут нет рисков, подобных плагину премодерации для mediawiki. Тут несколько иные риски, что в эти расширения подсунут тройн (подобные случаи вроде бы даже были, только засовывали не троян, а adware) Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
Sergey Gilfanov Опубликовано 11 января, 2015 · Жалоба Кривость рук писателя, конечно, влияет. Но инструмент влияет тоже. вики сильно способствует кривому написанию. К 'связный длинный текст' подходят все-таки с большей аккуратностью. Ну и еще про инструменты и премодерацию - не забываем про DCVS. Назначить кого-нибуть главным - и пусть он правки мержит. Заодно можно будет иметь слегка отличающиеся версии документации для разных ветвей проекта. И не очень запутываться в 'а вот этот параграф нужно исправить везде'. Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...
vodz Опубликовано 11 января, 2015 · Жалоба Мне вики нравится самим принципом, благодаря которому конкурента им нет и не нужно. Коллективным разумом решается как описать понятие кратко и ссылочно. А на всякие многостраничные тупые доки от производителя, щедро сдобренные маркетингом, где всегда упираешься в кучу проблем либо не расскрытия тонкостей, либо забалтывания - быстро появляются миллионы FAQ, "XXX изнутри", "для полных чайников", тысячи форумов пользователей, как от самих разработчиков, так и всяких весьма спорных хабрахабров. Вставить ник Цитата Ответить с цитированием Поделиться сообщением Ссылка на сообщение Поделиться на других сайтах More sharing options...