В этой статье обсуждается один подход к написанию пошаговых руководств. Хотя основное внимание здесь уделяется NETTUTS, большая часть подхода может быть применена для любого сайта. Если вы планируете писать учебные пособия для NETTUTS, вам следует прочитать / просмотреть эту статью. В PSDTUTS есть также параллельная статья, написанная редактором Шоном Ходжем, которая вдохновила его.
Набор навыков
NETTUTS — это учебники для веб-разработки. Это означает кодирование на основе веб-браузера, которое требует, по крайней мере, понимания HTML, немного CSS и некоторого языка веб-кодирования. Все остальное зависит от того, что будет освещено в вашем уроке. Это может быть кодирование платформы CMS / блога, PHP, библиотеки JavaScript, фреймворки CSS, базы данных и т. Д.
Вы, наверное, заметили, что самые популярные уроки здесь посвящены веб-разработчикам с элементом design-y. Поэтому знание того, как использовать графическое программное обеспечение, такое как Photoshop или Fireworks, может помочь. По крайней мере, знайте, как получить снимок экрана, поскольку это минимум, который вы хотите включить в учебник для визуальных элементов.
Запланируйте и имейте контрольный список
Вы не должны быть действительно формальными, но вы должны спланировать свое руководство и применить контрольный список. Вот рекомендуемый контрольный список, хотя вы можете изменить его по своему вкусу:
- Запланируйте свой урок.
- Запишите свой контрольный список.
- Исследуйте любые библиотеки кода, плагины, методы.
- Определите набор функций вашего демо-кода.
- Напишите свой код, протестируйте и доработайте его, пока не будете удовлетворены.
- Напишите учебный текст.
- Включите свой демонстрационный код в фрагменты, в учебное пособие (согласно нашим Руководствам по учебному пособию).
- Перечислите все недостатки кода, которые вам известны. (Т.е. не работает в Internet Exploder 6.0+ и т. Д.)
- Предоставьте подходящие визуальные элементы (изображение, скриншот, анимация и т. Д.) Не более 600 пикселей.
- Отредактируйте учебный текст и пронумеруйте каждый раздел с помощью «Шаг 1», «Шаг 2» и т. Д.
- Если вы использовали изображения, которые вам не принадлежат, вы должны не только давать атрибуцию, вы должны иметь либо неявное (например, CC-лицензию на Flickr), либо явное разрешение на их использование. Это включает в себя изображения, видимые в вашем уроке и в вашей демонстрации.
- Подготовьте исходный код для скачивания и запакуйте его. В этот же ZIP-файл включите рабочие демонстрационные файлы.
Облегчи себя
Существует несколько способов публикации в NETTUTS. Один из способов — отправить ваши рабочие демонстрационные файлы, исходный код, текст учебника и изображения (все вместе в формате ZIP) вместе через ссылку на форму на странице « Руководства учебника». Таким образом, вы получите ответ намного раньше, но вам предстоит проделать большую работу, если он не подходит для NETTUTS. (Это все еще рекомендуется, если вы никогда не отправляли учебник.)
Облегчи себя. Вместо того, чтобы сначала писать демо-код и учебник, сначала предложите идею. На самом деле это рекомендуется, если вы ранее отправили полное руководство, даже если оно не было опубликовано:
- Придумайте идею и отправьте ее мне, воспользовавшись ссылкой на форму на странице «Руководства по обучению». (Используйте пустой ZIP-файл, поскольку форма требует его.) Или, если вы ранее отправили мне идею / учебное пособие, у вас есть мой адрес электронной почты NETTUTS, и вы можете отправить мне сообщение напрямую.
- Если вы ранее не писали учебник для сайта, есть несколько этапов:
- Интерес к вашей идее не обещает публикации. После подачи идеи и получения интереса вам нужно будет показать демонстрационный код (даже если только на вашем собственном сервере).
- Если вы делаете демо-код и он подходит для NETTUTS, я спрошу вас — но не буду запрашивать — хотите ли вы написать учебник, но без гарантии публикации.
- Обратите внимание, что это звучит несправедливо, но на самом деле ничем не отличается от того, если вы отправите полный учебник заранее. Таким образом, у вас есть несколько этапов, на которых вы можете изменить свое мнение, сокращая ваши общие усилия. Если вы хотите отправить учебник и файлы заранее, это тоже хорошо.
- С другой стороны, если вы уже написали хороший учебник, требующий небольшого редактирования, я буду более снисходительным. Вы можете выдвинуть идею, получить мое желание, и написать учебник.
В любом случае, если демонстрация показывает потенциал, но учебник нуждается в работе, я постараюсь работать с вами на ограниченной основе, чтобы улучшить текст. Однако я не могу написать это для вас. Куча фрагментов кода и некоторый текст, который только функционально описывает происходящее, не является руководством.
Сделайте это проще в редакторе
По мере роста читательской аудитории NETTUTS у меня будет меньше времени, чтобы оценить, подходит ли учебник для NETTUTS. Облегчи мне, заставь меня хотеть использовать твой урок и демо:
- Используйте свое настоящее имя и адрес электронной почты в представлении. (Вы также должны иметь учетную запись PayPal, чтобы мы могли заплатить вам.)
- Четко опишите, что покажет ваше руководство, и что продемонстрирует ваш демонстрационный код.
- Отправьте демонстрационный код, который работает и не требует от меня много настроек (помимо загрузки некоторых файлов на сервер).
- Не присылайте мне демонстрационный код, который требует, чтобы я добавил свои собственные изображения или что-то еще, особенно если вы не хотите сказать мне заранее. Мое желание помочь вам сталкивается с нехваткой времени.
- В целом, минимизируйте количество времени, которое я должен потратить на настройку демо-кода, просто чтобы оценить его. Чем больше усилий требуется, тем больше вероятность, что оно будет отклонено. (Вы всегда можете начать с демонстрации на одном из своих сайтов, хотя в конечном итоге вам нужно будет предоставить мне файлы.)
Поставь себя на мое место и подумай о том, что заставляет меня хотеть принять твой урок. Не передавайте мне серию, если вы еще не приняли учебник и не опубликовали его. То же самое относится и к сериям между сайтами (т. Е. Часть 1 для PSDTUTS, часть 2 для NETTUTS).
Опишите каждый шаг тщательно
В конечном итоге учебник предназначен для читателей сайта, а не для меня. Если заголовок учебника привлекает их, и если они прочитали учебник после просмотра демоверсии или даже исходного визуального изображения (изображение, диаграмма и т. Д.), То они хотят учиться. Хотя вам не нужно держать в руках и описывать каждую строку кода, как если бы читатель никогда не кодировал ранее, вам нужно описать строки кода, относящиеся конкретно к любым библиотекам, плагинам или специальным методам, которые вы используете.
Самая большая проблема с представлениями на данный момент: использование библиотеки кода или плагина, показ фрагмента кода, но не описание соответствующих строк кода. Сказать «вот код для X» недостаточно. Зачем читателю беспокоиться о вашем уроке, если вы не раскрываете инструкции?
Тон и стиль письма
Прежде чем вы отправите настоящий учебный текст, прочитайте некоторые учебные пособия Collis здесь, в качестве отправной точки. Хотя хорошо иметь свой собственный стиль, вы также должны помнить, что большинство читателей сайта имеют (или много) опыт веб-программирования. Поговори с ними, а не с ними. (Я многословный тип, который происходит из-за того, что я был ассистентом / преподавателем в колледже для людей, не являющихся студентами, проходящих обязательный компьютерный курс.)
Руководство и форматирование
Уже есть страница Tutorial Guidelines , на которой есть ссылка на пустой учебник ZIP. Обратитесь к этой странице и используйте этот шаблон ZIP.
Определитесь с вашей темой
Вы действительно знаете, какой учебник вы хотите сделать? Не выделять здесь никого, но из нескольких представлений у меня сложилось впечатление, что человек просто хотел, чтобы пух в его кепке был опубликован на сайте, подобном NETTUTS. Их описание учебника и демонстрационного кода было расплывчатым, и, несмотря на то, что я пытался что-то предпринять, они не кусались.
мозговая атака
Один из лучших способов планирования и создания учебного пособия — набросать ваши идеи и наметить как функции, так и то, что вы демонстрируете. Поскольку учебные пособия по NETTUTS основаны на коде, у вас есть дополнительное требование наличия функционального кода для представления. Вот мой предпочтительный процесс создания учебника — но не забудьте контрольный список, упомянутый ранее:
- Мозговой штурм несколько идей приложений.
- Исследуйте необходимые библиотеки, плагины, функции, ограничения и т. Д.
- Обрисуйте в общих чертах нужные функции, наброски или макеты экранов браузера. (Помните, что вы можете использовать снимки готовых макетов в своем уроке.)
- Напишите код, протестируйте и доработайте его. (Тест в Browsershots, описанный в следующем разделе.)
- Напишите учебное пособие вокруг своего кода и включите фрагменты в легко усваиваемые куски, отформатированные в соответствии с Руководством по учебному пособию.
- Отредактируйте учебник, если это необходимо. Поставь себя на ум читателя. Если они обращаются к вашему руководству, потому что заголовок привлек их внимание, то они, вероятно, не поймут ваш код без надлежащего объяснения. Не просто показать блок кода и предположить, что читатель должен понимать. В противном случае вы пишете код, а не учебник.
- Добавьте визуальные элементы (скриншоты и т. Д.). Смотрите раздел Visuals ниже.
Демо-код и кросс-браузерные проблемы
Хотя было бы неплохо, чтобы ваша демонстрация работала во всех браузерах, это не всегда возможно. Некоторые библиотеки кода — например, jQuery — просто не поддерживают старые браузеры. По крайней мере, ваш код должен работать для браузеров, которые поддерживают библиотеки, которые вы используете.
Между прочим, несмотря на протесты в виде комментариев некоторых читателей NETTUTS, Firefox 3 не широко использовался на момент написания этой статьи. По словам некоторых пользователей Твиттера и Плюрка, он также глючит и по-прежнему вызывает проблемы с памятью. Мы должны будем рассмотреть совместимость браузера в каждом конкретном случае, но постараемся охватить самые последние стабильные браузеры. Укажите, если ваш код где-то не работает, и почему это так.
Одним из инструментов, который поможет вам в кросс-браузерном тестировании, является сайт Browsershots , который является простым способом протестировать ваш код в нескольких (виртуальных) браузерах для Linux, Windows, Mac OS и BSD.
Визуальные
В отличие от нашего родственного сайта PSDTUTS, когда дело доходит до учебников по веб-разработке, придумывать сексуальные образы не всегда легко. Тем не менее, визуальные эффекты делают учебник более интересным, а также помогают демонстрировать концепции. Так что визуальные эффекты в вашем уроке просто необходимы, и вам, возможно, придется проявить творческий подход. Вот несколько вариантов:
- Соответствующее изображение.
- Снимки экрана вашего приложения в различных состояниях использования.
- Скриншот вашего приложения или что-то, имеющее отношение к вашему уроку.
- Диаграмма или карта разума, представляющая некоторую информацию о вашем приложении, его использовании или дизайне и создании.
- Соответствующий видеоконтент, может быть, даже демонстрация вашего демонстрационного кода.
Включайте визуальные эффекты как можно чаще и на ранних этапах обучения. Во многих уроках, от которых я отказался до сих пор, не было изображений. Нетрудно сделать снимок экрана используемого приложения или макета экрана, создаваемого в Photoshop, или что-то еще релевантное. Вам не нужны десятки визуальных эффектов, но даже нескольких разумно выбранных снимков экрана может быть достаточно.
Примечание . Если вы используете визуальные элементы из других источников — либо в тексте учебного пособия, либо в демоверсии — вы должны иметь явное или неявное разрешение и ссылаться на источник (и). Например, вы можете использовать изображения из источника, такого как Flickr, под соответствующей коммерческой лицензией CC.
Процитируйте свои источники
В дополнение к предоставлению изображений, убедитесь, что вы зачислили любые библиотеки кодов, исходные тексты и т. Д. Это не означает, что вы можете представлять чужой код как свой собственный, а скорее, если у вас большое учебное пособие и вы используете технику, первоначально представленную кем-то другим, поверьте им.
статьи
В дополнение к учебникам мы публикуем одну статью в неделю, связанную с веб-разработкой. Вклад статьи один раз в две недели. Ресурсные статьи являются хорошими кандидатами, такими как моя статья о CSS Grid Framework, хотя ваша не обязательно должна быть такой длинной.
Я предпочитаю принимать предложения для статей от людей, которые являются опытными авторами / блоггерами, хотя вам не нужно писать учебник, так как стиль другой.
отклик
Я стараюсь отвечать всем как можно быстрее, хотя через несколько недель объем представлений достаточно высок, так что мне легко потерять след. Будьте уверены, я отвечу, хотя вы можете подтолкнуть меня, если вы не получили ответ через пару недель после подачи идеи или учебника.
Вывод
Я с нетерпением жду продолжения идеи и представления читателей NETTUTS. Если вы не знаете, с чего начать, учебники Collis здесь, в NETTUTS и PSDTUTS, являются отличной моделью для подражания, как с точки зрения снимков экрана, так и с точки зрения кодирования и стиля написания.