Перевод статьи «How to write a coding tutorial».


Технические руководства играют большую роль в процессе изучения программирования и создания программ. Я уверен, что руководства, созданные другими людьми, принесли вам много пользы, что благодаря им вы стали лучшим программистом чем были и можете теперь делать вещи, которые раньше были вам недоступны.
Читать руководства полезно, однако еще больше пользы может принести их написание. Когда вы создаете технические туториалы,
- это заставляет вас строить что-нибудь (маленькое и простое), относящееся к изучаемой теме, а это может послужить первым камнем в более сложном и подходящем для портфолио проекте;
- вы помогаете другим людям изучать то же, что изучаете сами;
- это позволяет вам «засветиться» в сообществе;
- вам поневоле приходится изучить предмет на достаточном уровне, чтобы объяснить его кому-то еще;
- это демонстрирует вашу компетентность, навыки коммуникации и т. п. потенциальным работодателям (партнерам).
Процесс написания туториала
1. Выберите технологию (инструмент, тему), которую вы хотели бы изучить и о которой хотели бы написать
Есть вещи, способные навести вас на дельную мысль при выборе темы. Попробуйте задать себе следующие вопросы:
- Какие технологии используются у вас на работе и в каких из них вы хорошо разбираетесь?
- Есть ли какие-то названия, которые у всех на слуху, но у вас все как-то руки не доходили исследовать эти вещи?
- Есть ли какой-то навык, которым вы не обладаете, но он часто попадается в объявлениях о вакансиях?
- Возможно, недавно вам нужно было что-то изучить и у вас возникли с этим сложности, потому что хороших руководств по теме не было?
2. Получше разберитесь в сути темы вашего будущего туториала
Записывайте, какие вопросы хотите осветить в своем руководстве.
Делайте закладки на полезные статьи, другие руководства, видео, документацию и т. п. вещи, чтобы в дальнейшем можно было легко к ним обратиться и указать в качестве ссылок в конце своего туториала. На этом этапе Google и официальная документация — ваши лучшие друзья.
Но не тратьте чересчур много времени на эти изыскания и не слишком углубляйтесь. Узнать побольше это, конечно, хорошо, но вам нужно двигаться дальше. К тому же, у вас будет возможность изучить много всего на следующих этапах.
3. Начните экспериментировать с кодом
Создайте какой-нибудь базовый проект, чтобы иметь возможность начать писать код. На этом этапе вам нужно поиграться с той технологией или инструментом, которые вы изучаете и о которых в конечном итоге собираетесь писать. Здесь не важны ни чистый код, ни определенная структура. Просто попробуйте на практике изучаемый предмет.
Когда освоитесь, начните обдумывать, как можно структурировать тот код, что вы пишете, для показа важных аспектов изучаемой вами технологии.
Если в ходе экспериментов вы столкнетесь с чем-то не слишком очевидным или таким, что стоит упомянуть, обязательно сделайте пометку об этом — это может пригодиться для использования в вашем туториале.
4. Создайте проект для туториала
Здесь вам пригодится опыт, который вы приобрели на предыдущем этапе. Возможно, это даже самая важная часть всего процесса — самая суть того, что ваша аудитория будет изучать.
Несмотря на обилие более сложных руководств, старайтесь делать все как можно проще: излишне сложные приложения могут отпугнуть вашу аудиторию.
Какого-то «правильного» способа создания подобного проекта нет, но хороший проект, подходящий для туториала, обладает определенными чертами:
- Это самый простой способ показать предмет изучения.
- Все должно легко настраиваться: никаких сумасшедших штук, в настройках которых можно заблудиться. Бойлерплейты вроде create-react-app прекрасно подходят для начала руководства, поскольку этот код будет знаком каждому, кто использовал React.
- Код проекта чист и хорошо организован.
- Проект имеет какую-то реальную тему для функционала, в отличие от абстрактных вещей вроде foo и bar. Но все не должно стать слишком сложным и замысловатым.


5. Создавая план вашего туториала, постройте проект еще раз с нуля
Ваша цель — организовать все, что вы делали до сих пор, в логичном порядке, чтобы в руководстве можно было показать линейное продвижение вперед. Старайтесь перестраивать проект таким образом, чтобы ваши пояснения в туториале шли плавно и не сбивали читателя с толку.
По ходу перестройки проекта сохраняйте сниппеты кода.
6. Преобразуйте план руководства в черновик
Вам нужно создать из пунктов вашего плана более полную версию туториала, с инструкциями, изложенными в виде полных предложений, с включениями сниппетов кода (где необходимо).
Пока не нужно беспокоиться об объяснениях концепций или выразительном тексте: на этом этапе достаточно скучного набора инструкций.
В итоге у вас должен получиться черновик, следуя указаниям которого вы сможете создать экземпляр проекта.
7. Украсьте свой черновик
Добавьте любые пояснения, цитаты, юмор, придайте своему руководству особый стиль. Обычно бывает хорошей идеей начать туториал введением читателя в контекст. Расскажите, для кого предназначено это руководство, почему вы решили его написать, какими знаниями должен обладать читатель, чтобы суметь разобраться в этой теме.
Также на этом этапе самое время добавить любые ссылки, которые вы считаете полезными. Добавлять можно как в текст, так и в начало или конец вашего руководства.
8. Представьте, что вы читатель, и пройдитесь по своему туториалу еще разок
Это как QA для вашего руководства. Попробуйте следовать указаниям в тексте, будто у вас нет никаких предыдущих знаний и опыта в этой теме. Старайтесь обнаружить любые шаги, способные вызвать затруднение у читателя: вполне возможно, вы воспринимаете какую-то информацию как нечто само собой разумеющееся! По ходу чтения редактируйте и упорядочивайте текст.
9. Публикуйте!
Опубликовать ваше творение можно в вашем собственном блоге, на techrocks.ru или какой-нибудь другой платформе. Главное, чтобы у читателей появился доступ к вашему руководству и они смогли им воспользоваться.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]