Βethan
В реальном мире, когда мы покупаем телефон, или микроволновую печь, или стиральную машину, мы получаем краткое руководство пользователя, руководство пользователя, некоторую техническую документацию и другие подобные вещи.
Без этих документов нам нужно будет научиться использовать продукт, используя исключительно метод «проб и ошибок», что совсем не приятно для пользователя.
То же самое относится и к продуктам и инструментам, созданным веб-разработчиками.
В последние несколько лет мы стали свидетелями огромного взрыва в мире веб-разработки.
Существует огромное количество отличных проектов. Поток плагинов, библиотек, фреймворков, инструментов и сервисов был создан умными людьми, демонстрирующими большую проницательность и умение.
Но есть одна проблема: у многих — возможно, у большинства — нет хорошей документации. Каким бы великолепным ни был конкретный продукт, если у него плохая документация, мы вряд ли будем использовать его полностью и правильно.
Целью данной статьи является рассмотрение важности наличия хорошей документации как для веб-разработчиков, так и для пользователей.
Я в основном ориентируюсь на программные продукты, такие как библиотеки кода, плагины и т. Д., Но все сказанное ниже может быть легко адаптировано к любому виду продукта или услуги. Принципы одинаковы.
Давайте посмотрим их.
Три шага к большому успеху
В мире веб-разработки есть три шага, ведущих к большому успеху.
- Создание отличного продукта . Прежде всего, вам нужно иметь что-то полезное и ценное, чтобы предложить людям там. Это может быть продукт или услуга, но в любом случае она должна быть высокого качества.
Еще одним важным фактором является простота использования. Даже отличный продукт может потерять свою ценность, если людям трудно его использовать. Завершение этого первого шага является большой вехой, но вы не должны останавливаться на достигнутом, как это делают некоторые веб-разработчики.
- Написание отличной документации . Вторым шагом является написание документации для вашего продукта или услуги. Просто представьте, что вы находитесь в красивой, но неизвестной стране.
Чтобы увидеть его достопримечательности, вам понадобится руководство, чтобы узнать, где они находятся, и карта, показывающая, как туда добраться. Руководство и карта из этого примера очень похожи на документацию вашего продукта.
- Предлагая отличную поддержку . Наконец, вам необходимо предложить подлинную поддержку для вашего продукта или услуги. Даже с хорошей картой и надлежащим руководством в вашем распоряжении будут случаи, когда вам потребуется руководство от реального человека, чтобы показать вам правильное направление.
Вот что такое поддержка. Если вы хорошо выполнили предыдущие два шага, то сделать это будет намного проще.
Учитывая вышеописанные три шага, мы можем легко вывести волшебную формулу для большого успеха:
Отличный продукт + Отличная документация + Отличная поддержка = Большой успех
Достаточно просто, верно?
Зачем вам нужна хорошая документация?
Парусный спорт «Следы: реальный на катушку» (Ронн на берегу)
Хорошая документация делает две важные вещи.
С одной стороны, это повышает ценность вашего продукта. Хорошо документированный продукт всегда предпочтительнее, чем с плохой документацией; потому что он более полный, более простой в использовании и, следовательно, гораздо более полезный.
С другой стороны, это уменьшает потребность в поддержке, потому что чем полнее ваша документация, тем меньше вероятность того, что у пользователей возникнут проблемы с вашим продуктом.
Еще одним важным моментом является то, что хорошо написанная документация повышает вашу репутацию.
Как? Плохая документация может позволить потенциальным пользователям просочиться к вашим конкурентам, чей продукт может быть не таким крутым, как у вас, но может быть лучше задокументирован.
Если я пользователь и вижу, что документация вашего продукта — отстой, то знаете ли вы, о чем я буду думать?
Если вы не заботитесь о своем собственном продукте, почему я должен?
Я переключусь на чужой продукт — кого-то, кто заботится о своем продукте и кто делает все возможное, чтобы создать для меня приятную пользовательскую среду, то есть облегчить его использование, предоставив исчерпывающую документацию.
Естественный вывод из вышесказанного: если пользователи увидят, что вы уважаете их и их время, вооружив их качественной документацией, то они, в свою очередь, будут уважать вас.
Что отличает профессионала от любителя, так это их внимание к деталям. Предоставление хорошей документации — одна из таких деталей.
Когда вы создаете отличный продукт, заманчиво остановиться здесь, думая, что этого более чем достаточно, и что ваш продукт будет говорить о себе автоматически. Но это не правда.
Какая польза от вашего супер-продукта, если никто не знает, как его использовать?
Значение NULL.
Итак, если вы хотите, чтобы ваш продукт действительно использовался, то вам нужно рассказать пользователям как.
Итак, что такое хорошая документация?
Далее следует набор условий и требований, необходимых для того, чтобы конкретная документация была классифицирована как действительно хорошая.
Хорошая документация делает несколько вещей:
- Он рассказывает, что такое продукт и для чего он может быть полезен (его определение и назначение).
- Это отличает другие аналогичные продукты (если таковые существуют) и то, что делает их уникальными.
- Он рассказывает пользователям, как начать работу с продуктом.
- Он рассказывает пользователям, как продукт может быть использован в реальных проектах (от простых до сложных).
- Он рассказывает, как продукт может быть использован наилучшим образом (лучшие практики).
- Это дает множество примеров и демонстраций для использования продукта.
Хорошая документация должна быть:
- Завершено Веб-разработчики должны предоставить документацию для каждой функции и каждого аспекта своего продукта, поэтому последний должен использоваться полностью и правильно. Все, что, если оно опущено, мешает пониманию пользователя, должно быть добавлено.
- Краткий Документация по продукту должна быть написана таким образом, чтобы устранить все лишние вещи. Все, что включено, но если оно опущено, не помешает пониманию пользователя, должно быть вырезано.
- Организовано . Каждый веб-разработчик должен иметь в виду, что случайно собранные учебные пособия и ресурсы — отсюда и там — не могут обеспечить систематическое, логичное, четкое и простое руководство. Все содержимое документации должно быть простым для отслеживания и навигации, с постепенной сложностью и четкой иерархией.
- Современный . Веб-разработчики всегда должны предоставлять актуальную документацию для самой последней версии своего продукта. Здесь нет оправданий!
Что такое фальшивка или псевдо-документация?
В приведенном выше разделе мы увидели, что такое хорошая документация, и зная, что мы можем легко понять ее противоположность: плохую или плохую документацию.
То, что я собираюсь показать здесь, это нечто иное. Я называю это фальшивкой или псевдо-документацией.
И лучший способ объяснить, что я имею в виду, это дать вам пару примеров.
Справочник по API
Как следует из названия, это просто «ссылка» или, возможно, «каталог».
Единственный вопрос, на который он отвечает: «Что?». Какие методы он содержит, какие свойства они имеют и так далее.
Там нет «Как?» вопрос в этом вообще.
Он не показывает вам, как использовать все эти методы и свойства. Он просто обрисовывает их в общих чертах так же, как таблица содержания описывает содержание книги. Его цель — помочь вам, когда вы уже освоили продукт (или, соответственно, прочитали книгу).
Он не может научить вас, как использовать продукт. Это только дает вам обзор своих возможностей и возможностей.
Итак, если вы думаете, что, предоставляя только ссылку на API для вашего плагина или библиотеки, вы предлагаете реальную документацию, вам лучше подумать дважды.
Документация, размещенная внутри файла кода
Некоторые веб-разработчики, как правило, используют комментарии внутри своих файлов кода в качестве источника документации.
Эта практика откровенно неверна.
Во-первых, потому что это не настоящая цель комментариев, а во-вторых, потому что это затрудняет процесс обучения.
Чтобы открыть файл кода, когда мне нужны инструкции, чтобы что-то сделать, это то же самое, как если бы я должен был открыть свое пианино, чтобы увидеть ноты, которые я хочу сыграть (потому что какой-то «умный» человек решил напечатать их внутри ).
Более того, излишние комментарии затрудняют чтение и поддержку кода. Продукт и документация должны быть разделены одинаковым образом, и по тем же причинам мы разделяем наши файлы HTML, CSS и JavaScript.
Вообще говоря, каждый раз, когда некоторые веб-разработчики (скорее всего, ленивые :)) пытаются «обмануть», результатом будет поддельная документация.
Кто отвечает за создание документации по вашему продукту?
Хороший вопрос, не правда ли? Итак, кто несет ответственность? Вы конечно. Как создатель, вы тот человек, который лучше всех знает ваш собственный продукт и то, как его можно использовать в реальных проектах.
Вам не нужно полагаться на сообщество и других людей, чтобы написать документацию и учебные пособия для вашего продукта. Это по нескольким причинам.
Во-первых, сторонние ресурсы, собранные здесь и там, не достаточно последовательны. Они не могут обеспечить четкий, логичный и цельный опыт обучения.
Во-вторых, сторонние учебники и статьи недостаточно надежны. Они могут быть неверными, устаревшими или даже удалены в какой-то момент времени.
И в-третьих, позволить кому-либо выполнять свою работу может также дискредитировать вашу репутацию.
Из каких компонентов состоит хорошая документация?
Хорошая документация может состоять из множества различных компонентов. Задача автора продукта — решить, какие из них включить. Чтобы упростить эту задачу, я могу предложить следующий список с некоторыми основными компонентами:
- Раздел «Начало работы». Первое, что вы должны сделать в своей документации, — это дать адекватный ответ на вопрос пользователя: «Как начать?». Это важно, потому что это помогает людям обрести уверенность и дает им отправную точку для дальнейшего обучения.
- Руководство пользователя / руководство — Если ваш продукт довольно сложный, то этот компонент абсолютно необходим. Это тип документации, которая дает пользователям исчерпывающую информацию о том, как конкретный продукт может и / или должен использоваться.
- Примеры / демонстрации — это чрезвычайно важный компонент. Если перефразировать знаменитое выражение — «Одна картинка стоит тысячи слов». — можно сказать, что один показанный пример лучше, чем тысяча указанных инструкций. Итак, главный принцип здесь: покажи, не говори.
Примеры / демонстрации дают реальное представление о продукте и его использовании. Почти каждая инструкция, особенно сложная, должна сопровождаться соответствующим примером.
- Код игровая площадка. Этот компонент предлагает готовую среду, в которой пользователи могут сразу начать играть с вашим продуктом. Это отлично подходит для быстрого опробования. Это важно, потому что для начинающих пользователей — которые еще не знают, будут ли они использовать ваш продукт — настройка их собственной рабочей среды может быть немного утомительной. В некоторой степени это похоже на концепцию «попробуй, прежде чем купить».
- Слайд-презентации. Слайды — это элегантный, лаконичный и понятный метод объяснения темы или концепции.
- Учебники — это один из широко используемых и эффективных способов обучения. Вы можете думать о них как о кратких руководствах / пособиях, ориентированных на более узкие темы.
- Скринкасты — Некоторые люди предпочитают видеоинструкции вместо письменных. Для них вы можете предложить видео уроки. А также, некоторые темы могут быть лучше объяснены, если они в формате видео. Вышеуказанный принцип — покажи, не расскажи — имеет здесь равную силу.
- Поваренные книги — они особенно полезны, когда вам нужно найти решение для определенных или общих проблем. Инструкции в форме рецептов ясны и кратки, и пользователи могут выбирать только те, которые им нужны.
- Справочник по API — Как я уже говорил ранее, это нельзя назвать истинной документацией, но все же это важная часть. Здесь важно то, как вы представляете API. Он должен быть создан понятным и легко обнаруживаемым способом, с удобной навигацией, а также с возможностью поиска определенного метода или свойства.
- Страницы / разделы часто задаваемых вопросов. Если вам необходимо уточнить некоторые сведения о вашем продукте или о том, что с ним связано, рекомендуется предложить страницу или раздел часто задаваемых вопросов.
- Системные требования. Прежде чем пользователи смогут запустить ваш продукт, он должен знать, возможно ли это для него. Поэтому убедитесь, что эта информация четко изложена и размещена на видном месте.
- Журналы изменений / заметки о выпуске. Просмотр пути вашего продукта от его концепции до недавнего внедрения может быть очень полезным для пользователей. Например, знание того, какие функции WordPress устарели, а что добавлено в его более новую версию, позволяет вносить необходимые изменения в тему, тем самым обновляя ее.
- Информация о лицензии — этот компонент сообщает пользователям, где они могут использовать ваш продукт и на каких условиях.
Конечно, приведенный выше список не является полным, но он дает вам хорошую основу для дальнейшего развития. Сколько компонентов вы будете использовать, зависит от сложности вашего проекта.
Если у вас есть небольшая служебная библиотека, состоящая из нескольких методов API, включая все вышеперечисленные предложения, будет слишком много. Вы должны решить самостоятельно.
Но во всех случаях вам нужно помнить одну вещь: идеальной документации не бывает.
Так что не нужно быть перфекционистом. Просто достаточно хорошо, это все, что вам нужно для достижения.
Где примеры хорошей документации?
Ниже приведены некоторые примеры, которые я считаю хорошей документацией.
Честно говоря, большинство из них не отвечают всем критериям, указанным выше, но гораздо ближе к ним, чем многие другие.
Список минимален и только для иллюстративных целей. Если вы считаете, что чья-то документация на продукт оставлена без упоминания, пожалуйста, не стесняйтесь добавлять ее в комментариях ниже.
Меньше
Less — чрезвычайно полезный продукт (препроцессор CSS), широко используемый во всех видах проектов, в которых используется CSS.
Кроме того, у него также есть отличная документация. Он предлагает раздел «Начало работы», полностью документированные языковые функции, полную ссылку на его встроенные функции, а также страницу, посвященную его использованию.
Последний дает много полезной информации о Меньшем использовании через командную строку и в браузере, поддержке браузера, Меньше компиляторов, редакторах с Меньше поддержки и средах, где используется Меньше.
jQWidgets
jQWidgets — одна из наиболее полнофункциональных и универсальных библиотек виджетов на основе jQuery.
Это не только отличный продукт, но и отличная документация. Каждый виджет четко документирован.
API для каждого виджета предоставляет примеры для каждого свойства, события и метода; плюс интерактивные примеры на jsfiddle.
Помимо виджетов есть также информация о том, как библиотека может быть интегрирована с другими популярными продуктами, такими как KnockoutJS, Bootstrap, WordPress и Joomla, PHP и ASP.NET, PhoneGap и так далее.
Кроме того, для каждого виджета существует множество демонстраций с предоставленным исходным кодом, что делает процесс обучения чрезвычайно увлекательным, простым и продуктивным.
KnockoutJS
KnockoutJS — еще один замечательный продукт (библиотека JavaScript) с обширной документацией. Он предлагает демо-видео, живые примеры, интерактивные учебные пособия и, по крайней мере, последнее, но не исчерпывающее руководство, подробно описывающее его возможности.
qooxdoo
qooxdoo — это универсальный JavaScript-фреймворк. Он предоставляет версии для веб, настольных компьютеров, мобильных устройств и серверов. Каждая версия хорошо документирована.
Например, на рабочем столе qooxdoo имеется полная справочная информация по API, полное руководство пользователя, доступное также в виде файла PDF, разделы по началу работы и разделы часто задаваемых вопросов и т. Д.
Также он предлагает некоторые интерактивные учебные пособия, игровую площадку с кодом, демонстрацию виджетов, браузер виджетов и демонстрационный браузер со множеством примеров.
CodeIgniter
CodeIgniter — это отличный PHP-фреймворк с небольшим размером.
На его домашней странице вы можете сразу получить ответ, что это такое и подходит ли оно для вашего проекта и требований. И, в его руководстве пользователя вы можете найти подробную информацию о платформе: начало работы, инструкции по установке, краткое руководство, ссылки на API и многое другое.
Одной из главных причин популярности CodeIgniter является четкая и краткая документация, которую он предоставляет. Иногда предложение слишком большого количества документации может быть ошеломляющим и запутывающим для пользователей, особенно если оно производится хаотичным образом.
Вот почему краткость так же важна, как и полнота.
Кто делает это неправильно?
Список будет длинным, без сомнения. Но я не хочу приводить здесь примеры плохой документации, потому что я не хочу никого называть и стыдить.
Но если вы внимательно прочитаете эту статью, вам будет очень легко распознать такую документацию, когда вы ее увидите.
Вывод
До сих пор мы видели, что хорошего продукта недостаточно для вашего успеха и для того, чтобы ваши пользователи / клиенты были счастливы.
Предоставление отличной документации — важный шаг на пути к успеху, и этот факт нельзя недооценивать.
Любой уважающий себя веб-разработчик должен доказать свой профессионализм, потратив дополнительное время на создание и предоставление достаточно хорошей документации. И я глубоко убежден, что эти дополнительные усилия окупятся довольно хорошо в будущем.