Интерактивная документация. Размышления.
Пишу по работе много документов типа Application Notes, в которых кроме вводных и заключительных слов чаще всего обьясняется на уровне "по шагам с картинками" какие параметры чего и где нужно изменить, чтобы все работало. Большей части коллег и клиентов этого хватает.
Однако находятся личности, в конце концов сьедающие львиную долю времени саппорта, считающие примеры, написанные в документе, обязательными параметрами или заявляющие, что им нужен "кулинарный рецепт" с указанием всех значений, а не AN. Типа "у вас в документации на скриншоте стоит IP 192.168.0.1, я его ввел и ничего не работает". Спрашиваешь: "А в какой сети работаете?", в ответ невнятное бормотание.
Самое первое, что происходит, когда звонит неподготовленный человек, это заполучить от него все, что он успел поломать. Для этого мы начали вставлять в AN чек-листы с указанием всех критичных параметров, который можно потребовать заполнить на той стороне и переслать нам для анализа. Какой-то процент юзерей отпадает на этом этапе, т.к. доходят до решения проблем сами, увидев список параметров.
Других же нужно "взять за руку и провести". Чорд, и это техники, благодаря которым без происшествий работает нефтехимия... нда. Но я отвлекся.
Давно уже грежу желанием написать интерактивную документацию типа: "На этом этапе введите IP адрес в то вон (указано стрелочкой) поле в проекте, затем введите то же самое в поле в этом документе", а тремя шагами далее, где нужно ввести второй IP "соседа", попросить то же самое и провести простейшую проверку. Или вместо текста "если тут поставить галочку, то надо ввести параметр Х, а если не ставить - Ы", сделать интерактивно: "Вы поставили галочку? Нажмите да или нет. Нажали нет - теперь введите Ы".
Заодно получаем документ, "заточенный" под конкретного пользователя, а не имеющего вид дерева возможностей "если вы используете то или это, переходите к странице 18".
А под конец из всего этого зоопарка сгенерировать проектную документацию в виде PDF-ки для архивирования.
И еще можно было бы это безобразие поставить на мобильники/планшеты сервисных техников и заполучать от них разом все.
Наверное, единственная проблема тут - поддержка такого "документа". Понятия не имею, как его сделать. На ум приходят только вебстраницы.
Однако находятся личности, в конце концов сьедающие львиную долю времени саппорта, считающие примеры, написанные в документе, обязательными параметрами или заявляющие, что им нужен "кулинарный рецепт" с указанием всех значений, а не AN. Типа "у вас в документации на скриншоте стоит IP 192.168.0.1, я его ввел и ничего не работает". Спрашиваешь: "А в какой сети работаете?", в ответ невнятное бормотание.
Самое первое, что происходит, когда звонит неподготовленный человек, это заполучить от него все, что он успел поломать. Для этого мы начали вставлять в AN чек-листы с указанием всех критичных параметров, который можно потребовать заполнить на той стороне и переслать нам для анализа. Какой-то процент юзерей отпадает на этом этапе, т.к. доходят до решения проблем сами, увидев список параметров.
Других же нужно "взять за руку и провести". Чорд, и это техники, благодаря которым без происшествий работает нефтехимия... нда. Но я отвлекся.
Давно уже грежу желанием написать интерактивную документацию типа: "На этом этапе введите IP адрес в то вон (указано стрелочкой) поле в проекте, затем введите то же самое в поле в этом документе", а тремя шагами далее, где нужно ввести второй IP "соседа", попросить то же самое и провести простейшую проверку. Или вместо текста "если тут поставить галочку, то надо ввести параметр Х, а если не ставить - Ы", сделать интерактивно: "Вы поставили галочку? Нажмите да или нет. Нажали нет - теперь введите Ы".
Заодно получаем документ, "заточенный" под конкретного пользователя, а не имеющего вид дерева возможностей "если вы используете то или это, переходите к странице 18".
А под конец из всего этого зоопарка сгенерировать проектную документацию в виде PDF-ки для архивирования.
И еще можно было бы это безобразие поставить на мобильники/планшеты сервисных техников и заполучать от них разом все.
Наверное, единственная проблема тут - поддержка такого "документа". Понятия не имею, как его сделать. На ум приходят только вебстраницы.