Как сказано в мануале

Материал из PhpWiki.

Перейти к: навигация, поиск

Введение

Многие начинающие программисты (не зависимо от изучаемого ими языка программирования) считают, что «профи» не читают мануал (или читают его крайне редко), потому что знают все наизусть. Это заблуждение. Без сомнения, люди с опытом помнят из мануала больше, чем начинающие. Но это не основной плюс, который приходит с опытом. Запомнить все невозможно, и мануал имеет свойство обновляться вместе с тем, что он описывает – какой толк с того, что этот «профи» помнит устаревшую информацию?

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

Как читать мануал?

Мануал читают четырьмя способами:

1. Если вы хотите знать больше, чем знете сейчас. Независимо от того, знаете ли вы много, знаете очень мало или ничего не знаете. Особенно полезен, если вы еще ничего не знаете или знаете очень мало. Читайте мануал так, как если бы вы читали какую-нибудь сказку. Просто ходите по страницам мануала и читайте все, что еще не читали раньше. Выделите 5% своего рабочего времени на такое чтение – это время вам потом с лихвой окупится.
2. Если вы решаете какую-то задачу и для ее решения нужно использовать какую-то функцию, но вы не знаете какую. Или вы знаете, какую функцию можно было бы использовать, но вам кажется (или, может, так оно и есть), что эта функция – не совсем то, что вам нужно. Найдите эту функцию (если не знаете, где ее описание, то воспользуйтесь способом, описанным ниже). И прочитайте все, что касается этой функции, в том числе ссылки в разделе «смотрите также» и комментарии пользователей. Если найденная функция не совсем вам подходит, то, возможно, ссылка на искомую функцию содержится в «смотрите также». В комментариях пользователей содержится много полезной информации, особенно по всяким нестандартным задачам. Как говорил один из моих шефов: «если перед вами возникла какая-то задача, то не сомневайтесь – до вас ее как минимум человек десять уже решали – просто найдите решение». Для такого чтения много времени не требуется и, следовательно, планировать его тоже не нужно.
3. Вы знаете, какая функциональность вам нужна, и знаете где про нее прочитать. Хотя названия функций и классов вы не знаете, но время поиска резко сокращается — вам надо только открыть мануал на нужном разделе и пробежать глазами пару страниц. Удивительно, но многие пренебрегают таким способом мануала, хотя он не занимает ни времени, ни «постоянной памяти» мозга.
4. Вы знаете, какая функция нужна для решения вашей задачи, но забыли ее имя и/или перечень/назначение аргументов или какую-нибудь особенность ее работы. В этом случае о чтении речь как бы и нет: вы просто «подсмотрели» какую-нибудь мелкую деталь. Это самый простой вариант и, думаю, он не нуждается в комментарии.

Многие начинающие программисты убеждены, что даже если опытный программист и читает мануал, то только последним способом (потому что забыл какую-нибудь мелкую деталь). Это заблуждение. Даже очень опытные программисты (и особенно они) читают мануал всеми четырьмя способами.

ПОМОГИТЕ! Не могу там ничего найти!

Итак, у вас появилась проблема.

При этом вы, честно говоря, ни черта в этом не понимаете и даже не подозреваете, с какой стороны подойти. Я не буду спрашивать вас, зачем тогда вы этим занимаетесь. Бывает. Итак, возьмем как пример PHP Manual – отличный пример хорошо структурированного и почти идеального мана. Откроем его. И что мы видим? Нет, можете не обращать внимания на имена-фамилии составителей (хотя не мешало бы и их запомнить). Я про то, что находится ниже и называется Table of Contents.

Надеюсь, вы себе представляете, что это. По-русски это звучит как «содержание». Теперь наступает время тяжелых размышлений: что нам, собственно, надо в мануале? И действительно, что мы там забыли? Возьмите свою проблему и подумайте, какие области из перечисленных в Table of Contents она затрагивает и какие области может затронуть решение.

Неплохо вообще-то понимать по-английски, хотя бы читать (да, перевод мануала уже есть, но он УЖЕ устарел, а за английским маном следит и обновляет ежедневно не один десяток людей). Подумали? Просмотрите главы мануала, которые вы выделили. Неплохо было бы еще просмотреть названия функций (обычно они «говорящие») и краткие описания рядом с ними. Обычно этого хватает, чтобы получить какие-то зацепки. От них можно уже отталкиваться дальше. Возьмем пример: всем уже приевшийся «постраничный вывод из базы».

Если подумать, то становится ясно, что: вывод каким-то образом связан с текстом, точнее со строками, еще точнее – со String functions. Если мы выводим что-то из базы, то надо искать в разделе, который ей посвящен (если у вас MySQL, то вам в MySQL Functions); проблема явно связана с математикой (арифметикой) – нам надо ДЕЛИТЬ общее количество на страницы.

Таким образом, шаг за шагом, мы приходим к функциям echo(), mysql_query(), mysql_fetch_*() (мы прочли ман и поняли, что mysql_result() не стоит использовать), мы посмотрели в Mathematical Functions и нашли там функцию ceil(), а также (по аналогии с многими языками и по подсмотренным в мане примерам) нашли конструкцию while(). Что нам еще надо? Ничего. Нам УЖЕ ничего не надо. Мануал – под рукой, пишем скрипт.

Что-то не работает – смотрим, почему, выводим переменные (print_r() нам поможет в этом), проверяем синтаксис функций и правильность нашего выбора. Вы спросите: «А где же тут форум? На каком этапе он появляется и зачем он вообще нужен?». А форум появляется только тогда, когда вы будете испытывать сложность в АЛГОРИТМЕ или сомневаться в оптимальности вашего алгоритма. Что же делать, если вы вообще себе алгоритм не представляете? Тут масса вариантов: бросьте, это не ваше; доучитесь, а потом беритесь; купите себе книжку, попробуйте почитать все сначала; прочтите, наконец, мануал. Запомните одно: в мануале есть МАССА ПРИМЕРОВ. Вам всего-то надо уметь искать и читать (надеюсь, что copy/paste вы сделать сможете?).

Ну вот вы чего-то не нашли в мануале (скорее всего плохо искали). И что делать? Да ничего. Сесть, успокоиться, открыть свой любимый поисковик и набрать ключевую фразу: «Как сделать так, как я хочу?». Уверяю вас – там будет масса попаданий.

Нет? Тогда открываем форум, жмем на ссылочку ПОИСК В ФОРУМЕ и пишем туда ключевые слова. Обратите внимание, что на форуме PHP-клуба при поиске находятся только те топики, в которых есть слова ровно в той форме, как вы задали в строке поиске. Например, если вы будете искать фразу типа «как хранить деревья», то в качестве результата появятся топики, в которых есть слово «как», слово «хранить» и слово «деревья». Если в форуме есть топик, в котором есть слова «как» и «хранить» и «дерево», но нет слова «деревья», то этот топик в результат не войдет. Пробуйте разные словоформы. Если есть топик, в котором есть слова «хранить» и «деревья», но нет слова «как», то этот топик тоже не будет показан в результате. Но ведь слово «как» Вас не интересует, не так ли? Используйте только самые важные слова. Чтобы искать по части слова, используйте звездочку: поиск по «дерев*» найдет все топики, в которых есть слова, начинающиеся на «дерев»: «дерево», «деревья», «деревянный», но не «древообразный».

Не нашли? Ну что ж, пишите в форум.

Внимание!

Перед тем, как писать в форум, обязательно прочтите правила форума и сделайте еще одну очень важную вещь – задайте себе тот вопрос, который вы хотите задать в форуме. 49% людей не могут толком задать вопрос, еще 49% могут ответить на него сами, но почему-то этого не делают, остальные 2 процента – это реальные вопросы. В последнее время эти 2 процента все чаще превращаются в вопросы типа «Я не умею читать, покажите мне строку, в которой написано «мама мыла раму»! Плииииз!»

Не стоит к ним присоединяться. Лучше пойдите, попейте кофе/чай/пиво/водку и подумайте. Если вы ПРАВИЛЬНО прочли ман, то ответ ДОЛЖЕН к вам прийти, надо только чуть-чуть подумать. Когда будете бить себя по лбу и кричать «Как же я сразу не догадался?!», не забудьте поставить на стол чашку/кружку/рюмку.

На что стоит обратить внимание

• Раздел «См. также». Многие умные люди работали над мануалом и написали в этот раздел страницы сходные или связанные с текущей страницей. Если вы немного промахнулись (нашли функцию округления числа вниз, а нужно округление с заданной точностью) — нужная вам функция может оказаться именно в этом разделе.
• Новые термины. Во-первых, они поднимают вашу эрудированность в предмете, что для программиста аналогично кубикам преса. Во-вторых, по ним можно искать. И находить.
• Коментарии к мануалу. Например, онлайновый мануал по PHP снабжен средством коментирования, где написанно много полезных советов в стиле cookbook (кулинарной книги).

Часто задаваемые вопросы

• Я знаю имя функции, но никак не могу найти ее описание.

Скачайте документацию в формате “Windows HTML Help” (*.chm):
http://www.php.net/download-docs.php

Запустите ее, на вкладке «Указатель» наберите имя функции и нажмите Enter.

Описание функции также можно найти, набрав в браузере:

php.net/имя_функции

Например,
http://php.net/mysql_fetch_assoc

• Что делать, если я не умею искать?

Шаг 1. Искать так, как если бы Вы умели искать. Забудьте слово «не умею».

Шаг 2. Выполнится автоматически после того, как вы много раз проделаете шаг 1. Умение придет с опытом.

• Я часто что-нибудь ищу, но так и не научился толком искать. Почему?

Есть такая пословица: без труда не выловишь и рыбку из пруда.

Несмотря на эту пословицу, многие хотят без труда выловить рыбку из пруда.

Вон, даже в «Матрице» обучение идет по ускоренной программе: вставили дискетку, пять секунд и вы уже умеете управлять вертолетом. Идея о таком способе обучения не на пустом месте возникла – она взята из жизни. Не забывайте о том, что в реальной жизни такого не бывает!

Если вы еще не научились – учитесь дальше!

• Что делать, если я не умею пользоваться расширенными возможностями поиска?

Нужно прочитать документацию по расширенным возможностям поиска – там все написано.

• Что делать, если я не знаю, где описаны расширенные возможности поиска?

Нужно найти то место, где описаны расширенные возможности поиска. Поиском для этого, кстати, пользоваться не требуется – просто посмотрите внимательно на страницу с формой для поиска, где-нибудь должна быть ссылка.

• Я ищу-ищу, но ничего не могу найти. Что делать?

Искать дальше. Попробуйте другие способы, другие ключевые слова, другие поисковые системы. Кстати, на форуме РНР-клуба можно искать не только при помощи формы поиска, которая есть на самом форуме, но и при помощи Яндекса и при помощи Google! Искать можно не только на форумах PHP-клуба, но и на других сайтах.

Находка, выдумка, смекалка вам помогут.

• Читать мануал как сказку? Разве такое возможно – ведь сказка – это интересно, а мануал – это так скучно!

Вы можете представить себе профессионального врача, у которого любимое увлечение – игра в футбол, а медициной он занимается только по принуждению? Представьте, что этот врач будет делать вам операцию. Что вы чувствуете?

Если вы считаете, что читать мануал – это скучно, то откажитесь от программирования вообще.

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

• Вы сравниваете нас с начинающими программистами. Вы хотите нам доказать, что мы ничего не умеем?

Я сравниваю не вас, а начинающих программистов с опытными. Если вы приписали себя к начинающим, а не к опытным, то вы сделали это самостоятельно.

Я привожу сравнения для того, чтобы вам было проще смотреть на все с точки зрения опытного программиста, даже если вы сами себя таковым еще не ощущаете. Припишите себя к опытным и смотрите с точки зрения опытного программиста. Забудьте о своей неопытности и ощущение опыта со временем придет к вам.

Нет ничего плохого в том, если вы только начинаете, еще ничего не знаете и не умеете. Плохо, если вы не хотите знать и не хотите уметь.

• Почему некоторым не нравится фраза: «ПОМОГИТЕ! Не могу там ничего найти!»

Потому что фактически эта фраза означает: «Не хочу больше искать. Найдите за меня!» Так и хочется добавить: «Я пришел. Обслуживайте меня!»

Дополнительная информация

http://www.php.net/docs.php

Главный вход в документацию по PHP.

http://dev.mysql.com/doc/

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

http://html.manual.ru/

Это не перевод скучной спецификации и не попытка написать учебник. Задача справочника – коротко и ясно описать действие всех элементов языка HTML, которые вы можете без опаски использовать при создании Internet-страниц, не боясь, что какая-то версия какого-либо браузера сделает вам неприятный сюрприз.

Иначе говоря, здесь представлен «классический» HTML, употребляемый профессиональными web-разработчиками. И ничего лишнего.

Все теги, не описанные в этом справочнике, можете смело выбросить в помойку.

http://webclass.polyn.kiae.su/konspekt.htm

Хорошие интерактивные учебники по JavaScript, CSS, заголовкам HTML.

http://msdn.microsoft.com/

MSDN – официальная документация по всем продуктам Microsoft, бесплатно доступная в режиме online.

Кроме всей прочей документации, здесь расположена самая полная документация по JavaScript, HTML, CSS. Только для Microsoft Intenet Explorer, и в основном на английском языке.

Для чего нужен форум?

Вы задали вопрос, а вас, вместо того, чтобы дать вам ответ, послали читать мануал? Вы считаете, что на форуме с вами обращаются несправедливо? Никто не захотел вам помочь, и теперь вы мучаетесь вопросом «а для чего же тогда вообще нужен этот форум?» Прочтите внимательно эту статью, и вы поймете, почему с вами происходит то, что происходит.

Copyright YuriPopoff, http://phpclub.ru/faq/

ремонт дверных замков. Со скидкой оформили государственный диплом техникума на этом сайте

Как написать хорошую инструкцию: 5 шагов, полезные советы, пример

Содержание статьи:

Имя собственный ресурс, для привлечения постоянного и качественного трафика, требуется размещать на нем полезный и нужный целевой аудитории материал. Таким материалом, практически всегда, является хорошая инструкция.

Инструкция — это некие указания, правила и порядок действия, для достижения какой-либо цели. Таких статей в сети Интернет тысячи и все они несут некую полезную информацию.

Как написать инструкцию — это вопрос больше к самому себе, так как написание хорошей инструкции полностью зависит от владения темой самого автора, но также существует некий план по ее написанию, придерживаясь которого можно создать действительно полезный материал для своего сайта или на заказ.

Для чего нужна любая инструкция

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

1. С точки зрения читателя — это решение его проблемы, в том или ином вопросе, в зависимости от тематики сайта, на котором она опубликована;
2. С точки зрения заказчика (владельца сайта) — привлечения целевого трафика, а как следствие потенциальных клиентов;
3. С точки зрения копирайтера — написание качественного текста, который принесет доход или упорядочит информацию в голове.

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

Какие бывают инструкции

Четких критериев и определений на то, какие бывают инструкции, вряд ли кто-то сможет дать. Это сугубо индивидуальная тематика и даже для решения одного и того же вопроса, инструкция может быть совершенно разной и подана в разных стилях, в зависимости от места размещения и контекста.

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

1. Инструкция по строительству или сборке чего-либо;
2. Инструкция по применению чего-либо;
3. Медицинская инструкция;
4. Инструкция из разряда «Как сделать…»;
5. Инструкция по приготовлению пиши (рецепт);

Естественно, это далеко не весь перечень, даже самых распространенных видов инструкций, но наиболее известный — это точно.

Существует отдельный вид инструкций, я его называю «специфический», к нему можно отнести:

1. Пошаговую инструкцию как написать книгу;
2. Инструкцию как в домашних условиях сделать что-то для этого не предназначенное;
3. Инструкция как вести себя в той или иной ситуации.

Как написать пошаговую инструкцию (самое интересное)

По сути, эта статья — инструкция как написать инструкцию, плюс неплохо заточенные под СЕО текст с ключами. То есть, структура, выделенные ключи и заголовке в этой статье — это уже первый пример инструкции.

Но, помимо всего, я все же расскажу начинающим копирайтерам, по какому плану следует идти, чтобы написать качественную инструкцию, гайд или свод правил:

1. Найдите проблему — это очень важный этап. Кроме того, проблема, которую решит ваша инструкция должна полностью соответствовать тематике вашего сайта или сайта заказчика;
2. Разобраться в вопросе — полностью, досконально и глубоко разобраться в вопросе, о котором будете писать инструкцию;
3. Разбить решение проблемы на шаги — составе план, в котором первым пунктом будет наличие проблемы, а последним описание результата ее решения. Промежуточными же пунктами должны стать, последовательные, четкие, полные и грамотные шаги по достижению цели;
4. Распишите более подробно каждый шаг — даже уже написав текст в него всегда есть что добавить. Пусть последовательность решения проблему будет максимально подробной;
5. Схемы, картинки, примеры — добавьте в статью максимально доступную визуальную информацию. Ее должно быть немного, но в тоже время и не мало. Но помните, что не для всех инструкций такой ход необходим, как, скажем, в этой;
6. Полезные советы — добавите вставки в текст с полезными советами (также не для всех видов инструкций);

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

Вы пришли сюда из поиска? Это доказывает вышесказанное.

Как написать инструкцию: пример

Как я уже говорил выше, пример написания инструкции — это вся эта статья. Более того, большинство статей на этом сайте, которые начинаются со слова «Как» — являются инструкциями, в той или иной степени.

Повторюсь еще раз, классификации и стандарта по написанию инструкций не существует. Главное в написании такого материала — это подробное и пошаговое решение проблемы читателя. Если читающий разобрался со своей проблемой, то инструкция написана верно.

Источник статьи: http://yourwriter.ru/articles/general-articles/how-to-write-a-good-instruction/

Как написать руководство пользователя: подробная инструкция

Поделитесь статьей, пожалуйста:

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

Исследуйте тему

Чтобы автору написать понятное руководство ему нужно самому хорошо разбираться в теме. Неважно — являетесь вы экспертом в области или нет, нужно обязательно прочитать информацию из разных источников. Или ещё раз освежить материал в памяти.

Чтобы инструкция получилась полезной копирайтеру нужно разбираться в отрасли на 100%, но описывать её с позиции новичка. То есть ставить себя на место читателя. Прочитайте аналогичные статьи на похожие товары. Это поможет вам лучше разобраться в структуре и стиле такого контента.

Разработайте план и напишите текст

После тщательного изучения материала можно приступать к планированию. Продумайте, с чего лучше начать и чем продолжить. На примере инструкции к пылесосу «Xiaomi mi robot vacuum cleaner» я расскажу о принципах написания такого текста.

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

Содержание руководства пользователя на примере инструкции к пылесосу

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

Описание продукта на примере инструкции к пылесосу «Xiaomi mi robot vacuum cleaner»

Не пишите специальные термины, понятные только узкому кругу читателей. Текст должен быть понятен любому. Если без этого никак — распишите каждый термин понятным языком.

Не используйте в работе личное мнение или собственный опыт пользования товаром. Инструкция — это документ, в котором структурно и чётко описаны шаги и действия.

Добавляйте в статью скриншоты. Наглядно понять работу программы или техники намного проще.

Добавляем скриншоты для наглядности (пример)

Пишите даже те моменты, которые кажутся очевидными и понятными без описания. Они понятны вам. Но не факт что и всем остальным тоже.

Уникальное предложение — -50% на ВСЕ курсы Skillbox. Получите современную онлайн-профессию, раскройте свой потенциал.

Пишите текст короткими предложениями с глаголами повелительного наклонения: «Включите компьютер», «Нажмите на кнопку…», «Включите в розетку…».

Пример написания текса для руководства пользователя к товару

Придерживайтесь логики и будьте последовательны. Например, при описании программного обеспечения для ПК: «Включите компьютер. Вставьте диск в дисковод…». Будет нелогично писать: «Начните работу с диском, затем включите ПК». Завершайте инструкцию ответами на частые вопросы и/или описанием неисправностей и как их устранить.

Рекомендации и советы по написанию руководства пользователя к любому товару на примере

После того как статья будет готова — дайте её прочитать другу или знакомому, и спросите, насколько она понятна. Так вы сможете исправить недочёты и испытать ваш текст в действии.

Источник статьи: http://checkroi.ru/blog/how-to-write-a-user-manual/

Как написать инструкцию так, чтобы тебя поняли

Есть такая поговорка: «Хочешь сделать хорошо — сделай сам».

Для себя, действительно, так будет быстрее и спокойнее. Однако любому руководителю известно, что плохой менеджер это тот, кто не умеет объяснять и делегировать полномочия. Соответственно, умение давать четкие инструкции и план действий — задача хорошего руководителя. А помогает ему в этом «юзабельность». Давайте и разберёмся с этим понятием.

Юзабилити (от англ. usability) означает удобство в использовании, эргономичность и легкость в понимании.

Инструкция для сотрудников — эффективная и легкая, если результат ее выполнения успешен. При подготовке статьи анализировались внутренние инструкции для сотрудников, выложенные на внутреннем ресурсе Wiki. Однако многие из них оставляют вопросы даже при подробном изучении материала.

Итак, а теперь непосредственно к главному.

Выражение: «И так сойдет» — точно не для инструкций.

1. Постановка цели: для кого и для чего инструкция предназначена. Здесь следует упомянуть, что не следует памятку перегружать терминологией, иначе к ней будет прилагаться словарь терминов — целая энциклопедия и, увы, мало шансов, что её прочитают.

2. Не используем в инструкции много сленга. Есть шанс, что не все сотрудники его поймут.
Пример: «Уточнить у манагеров, получила ли апрув статья». С одной стороны, написано всё понятно, но для официального документа такой сленг не подходит.

3. Текст разбавляем скриншотами. Их желательно делать на своем компьютере и в той программе или интерфейсе, который есть у всех сотрудников. Возможно редактирование скриншотов стрелками и выделением цветом пунктов.

Примеры скриншотов с вполне понятными шагами:

4. Не пропускаем шаги, которые кажутся нам слишком простыми. Пусть лучше сотрудник, читая инструкцию, сам пропустит этот степ.

5. В тексте нежелательно использовать большие предложения. Коротко: «Зайдите в меню», «Добавьте значение…», «Выберите параметр…» и т.д.

6. Для сокращения объема текста возможно применение графических элементов. Например,

Local area connection ——> properties—>TCP/IPv4—>properties.

7. Применение шрифтовых выделений допустимо. Это привлекает внимание на особо важных пунктах.

8. Не используйте в инструкции ничего из вашего личного опыта применения того или иного продукта или использования программы. Для этого существуют отдельные встречи с сотрудниками, где вы передаете им свой ценный опыт. А инструкция — это логичная структура, где описан «шаг — действие» и ничего более.

9. Будьте точны и логичны в написании. Помните, если сотрудник, работая по вашей инструкции сделает ошибку, то это будет ваша недоработка.

Эффективная юзабельная инструкция — это не простая формальность, это один из шагов к успешности и автоматизации рабочего процесса. Зеркальный юзабилити эффект заключается в том, что вещи, которые имеют отношение к собственного опыту, мы запоминаем лучше, чем те, которые не имеют к нам никакого отношения. Поэтому написание инструкций и памяток прокачивает менеджерские навыки специалистов. А это, в свою очередь, идет в «копилку скилов».

Источник статьи: http://habr.com/ru/company/icl_services/blog/421503/

Мануал что это такое, для чего нужен и как его составить (написать, сделать)

Здравствуйте, уважаемые читатели блога: My-busines.ru. Из содержания предлагаемой вашему вниманию статьи вы сможете узнать о том, что такое мануал.

Что это такое

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

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

Для чего нужен

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

Формат

Наиболее распространенными являются следующие форматы: PDF, Word, HTML. Рассмотрим каждую из этих разновидностей форматов более подробно.

PDF-формат наиболее распространен, потому как он является межплатформенным. Изначально данный формат был создан фирмой Adobe Systems с использованием специального языка PostScript. Наиболее подходящей программой для открытия данного формата является Adobe Reader.

В формате Word мануал обычно пишется в тех случаях, когда имеется необходимость в специальных символах, абзацах, шрифтах, медиафайлах.

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

Как составить (написать, сделать) мануал

Написание грамотного мануала включает в себя следующие этапы:

1. Указание темы. В границах и сфере темы необходимо быть предельно внимательным и точным;
2. Определение аудитории, для которой составляется (новички, профессионалы, люди со средними знаниями, будут ли изучать самостоятельно или же коллективно);
3. Выбор количества разделов;
4. Выбор названий разделов;
5. Выбор логической структуры изложения материала. Взаимосвязь разделов должна определяться исходя из последовательности действий;
6. Составление словаря терминов, если планируется использование специальных жаргонизмов. Его необходимо будет обновлять по мере написания;
7. Определение тем, которые требуют дополнительного исследования. Если вы не уделите подготовке мануала должного внимания, то от него не будет абсолютно никакой пользы. По этой причине очень важно закончить проведение различного рода дополнительных исследований до того, как вы приступите к написанию;
8. Определение структуры каждого из разделов;
9. Организация логической последовательности каждой секции и каждого раздела, постепенно сужая границы темы.

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

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

Изображения обязательно должны быть подогнаны под размеры текста.

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

После того как мануал будет написан, обязательно все проверьте. А еще лучше перепроверьте. И желательно не один раз. В случае обнаружения каких-либо ошибок немедленно исправляйте их. Также очень важно делать заметки об обнаруженных ошибках. Если вы считаете, что какой-то раздел может показаться другим людям непонятным, лучше его переписать. Также имеет смысл дать прочитать написанный вами текст разным людям. Только так вы сможете удостовериться в том, что написали все правильно.

Проверять готовый мануал лучше всего в следующей последовательности:

• самостоятельная вычитка на предмет обнаружения ошибок;
• вычитка посторонним человеком;
• вычитка специалистом в соответствующей области;
• вычитка руководителем если он пишется для организации.

Также имеет смысл дать прочитать только что написанный вами мануал не разбирающемуся человеку. Так вы сможете узнать насколько написанный вами текст является понятным для непрофессионалов.

Источник статьи: http://my-busines.ru/useful/manual-chto-jeto-takoe-dlja-chego-nuzhen-i-kak-sostavit-napisat-sdelat-manual

---

Пользовательская документация  —  не самая интересная тема для разработчиков. Однако важно убедиться, что продукт не причинит вреда пользователям  —  ни физически, ни в плане повреждения их собственности. Утрата данных, выход из строя оборудования и прочие проблемы могут привести к серьезным судебным претензиям. 

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

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

Определить целевую группу

Прежде чем начать писать документацию, необходимо определить, для кого она будет предназначена? Кто будет использовать продукт?

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

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

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

Этот список далеко не полон и показывает только то, что для написания понятного руководства необходимо понимать его будущих читателей.

Понять, как будет использоваться продукт 

Когда с целевой группой пользователей вы определились, нужно понять, как именно они будут работать с продуктом. Хорошая документация всегда должна ориентироваться на пользователя, а не просто объяснять функционал. Технические писатели создают мануалы, ориентированные на задачи, а не на функционал.

Вот два примера, которые помогут выделить отличия этих двух принципов.

• Функционально-ориентированное название главы: “Использование мастера экспорта”.
• Задачно-ориентированное название главы: “Экспортирование данных проекта”.

В данном случае мастер экспорта  —  это просто инструмент для выполнения задачи, а именно экспорта данных. Пользователи не знают, что для экспорта данных им нужно использовать мастера экспорта. Они будут искать, ориентируясь на задачу, а не функцию.

Разработчики же работают с функционалом, поэтому переключение на восприятие с позиции выполнения задачи может вызывать трудности.

В этом случае рекомендуется спросить себя следующее.

• Что будут делать пользователи с продуктом?
• Почему они его используют? Какова их цель?

Лучше всего будет пригласить группу пользователей и провести с ними обсуждение. Целью будет определить их задачи и, в идеале, дать им название на языке пользователей. Если же возможности собрать группу реальных пользователей у вас нет, то есть еще одно решение: пригласить коллег, которые по своей работе близко с ними связаны (например, продакт-менеджеров, проектных менеджеров, маркетологов или специалистов поддержки).

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

Начните с инструкций

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

Инструктивная глава дает пользователю пошаговый алгоритм действий.

Советы по написанию инструктивных глав

Вот несколько советов, которые нужно учесть при написании инструктивных глав.

• Начинайте название главы с существительного. Пример: “Экспортирование данных проекта”.
• Структурируйте инструктивные главы в виде нумерованного списка. Каждый этап задачи должен представлять один пункт списка.
• Инструктивная глава не должна превышать 11 шагов. Большее число шагов излишне ее удлинит, снизив удобство чтения. Если в итоге у вас получается длинная глава, то поделите ее на подразделы.
• Описывайте шаги в императивной форме. Пример: чтобы экспортировать данные проекта, нажмите на значок “Экспорт”.
• Не предоставляйте подробной информации о возможности продукта или о том, как он работает. Вместо этого сосредоточьтесь на выполняемых пользователем шагах. Главы с сопутствующей информацией относятся к следующему этапу руководства.

Далее приводится пример того, как должна быть отформатирована и написана инструктивная глава.

Пример инструктивной главы

Добавление сопутствующей информации

После написания инструкций спросите себя: “Что нужно знать пользователям (чего они еще не знают) для выполнения всех этих инструкций?”

Перед каждой инструктивной главой добавляйте концептуальные. Они будут объяснять особенность ПО, необходимую для выполнения инструкций. В примере “Экспортирование данных проекта” одна глава может быть посвящена мастеру экспорта и поддерживаемым форматам данных.

Инструктивная и концептуальная информация строго разделяются, упрощая для пользователя поиск нужной информации. Помните, что большинство пользователей не читают все руководство, а ищут конкретную тему, используя функцию поиска или службу поддержки.

Советы по написанию сопутствующей информации

Вот несколько советов, актуальных при написании концептуальных глав.

• Не добавляйте в заголовках описательные приставки типа “О…” или “Сведения о…”. Называйте только сам принцип или функцию, которую хотите описать. Почему? Когда вы ищете что-либо по теме в интернете, то не вводите “Сведения о затмении”. С большей вероятностью вы будете искать по запросу “Затмение”. Когда пользователи ищут принципиальную информацию, они действуют аналогично, например пишут запрос “Мастер экспорта”.
• Добавляйте только такие концептуальные главы, которые помогут пользователям выполнить инструкцию. Вероятно, вы вложили немало усилий в разработку бэкенда, необходимого для работы конкретной функции. При этом сложности, связанные с ее реализацией, не должны отражаться в документации. Единственное исключение  —  когда пользователю нужно знать эти детали для выполнения инструкций. Перед написанием концептуальной главы всегда спрашивайте себя: “Зачем пользователю нужно это знать?”.
• Связывайте описательные главы с соответствующими инструктивными и наоборот.

Пример главы с сопроводительной информацией

Добавление справки

Последний компонент  —  это справка. Справочные главы содержат информацию для поиска в виде таблиц. В этих таблицах вы описываете графический интерфейс пользователя (GUI) и API.

Этот тип информации предназначен для пользователей, которые знакомы с принципом в общем, но хотят почитать о параметре, поле записи, выпадающем меню или других элементах GUI. В первую очередь такие справочные главы ориентированы на опытных пользователей, хотя иногда их читают и новички.

Советы по написанию справочной информации

• Заголовок справочной главы должен совпадать с элементом GUI или описываемой в ней функцией, например “Диалоговое окно мастера экспорта”.
• Обязательно называйте элементы GUI так же, как они названы в самом GUI. Пользователи зачастую копируют названия элементов и вставляют их в строку поиска.
• Подумайте, какая информация поможет пользователю, ищущему конкретный элемент GUI. Возможно, он как-то связан с другими элементами GUI или ограничениями. Задокументируйте их в справочной главе.

Примеры справочных глав

---

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

Я не стал детально объяснять, почему рекомендую структурировать и писать руководства именно так. Моей целью было научить вас делать это максимально быстро. 

При этом нужно иметь в виду, что даже идеально структурированная документация ничего не стоит, если само содержание читать невозможно. Так что не забывайте основы.

• Используйте проверку орфографии.
• Пишите последовательно.
• Используйте короткие и понятные предложения.
• Используйте как можно меньше слов, только их необходимое количество.

Помните, что мануалы мы читаем не ради удовольствия, а от необходимости.

Читайте также:

• 5 вредных привычек неэффективных программистов
• Как написать хороший README: краткий курс
• Успешный релиз ПО: распространенные ошибки перед запуском продукта

Читайте нас в Telegram, VK и Яндекс.Дзен

---

Перевод статьи Andreas D.: How To Write Manuals as a Developer

( 3 оценки, среднее 4.67 из 5 )