Написано Гурлин Сетхи, вы можете найти меня в LinkedIn, Medium, GitHub.
Простой процесс написания технических статей
Написание технических статей не так просто, как может показаться. Многие думают, что все, что вам нужно сделать, это «записать кучу вещей, и готово». Разработчики, которые написали статью или пытались ее написать, знают, как сложно и утомительно написать хорошую статью.
Опубликовав более 50 технических статей, я обнаружил, что для стабильного (и быстрого!) Выпуска качественных статей вам нужен процесс.
В этой статье я поделюсь очень простым процессом, который использую при написании технических статей.
Что за процесс?
Не пугайтесь слова «процесс». Это очень простые шаги, которым я следую всякий раз, когда мне нужно написать статью. Эти шаги позволяют мне быстро «подготовить» статью.
Вы: «Так зачем мне процесс?»
Я: Ну, наличие процесса устраняет одну из самых больших проблем с чем-либо, то есть с «началом работы». Самая большая проблема при написании статьи - понять, как и с чего начать. Если вы удалите это препятствие, все станет намного более управляемым.
«Процесс» (или шаблон)
0. Заголовок на первом месте 🥇
Прежде чем написать одно-единственное слово, вам нужно сообразить, о чем вы хотите написать. Самое первое, что нужно сделать, - это выбрать название, хотя это может показаться очень тривиальным делом, но это очень важно. Правильный заголовок дает вам направление при написании статьи.
Есть разница между «Как использовать Redux с React» и «Redux с React». В одном ясно сказано, что это учебное пособие, а в другом - не очень.
1. Сбор информации ℹ️
Соберите всю информацию, которая, по вашему мнению, вам понадобится при написании этой статьи. Сюда входят ссылки на другие веб-сайты, руководства, документация, образцы кода, изображения. Все, что имеет отношение к этой статье, держите «на расстоянии одного клика».
Откройте текстовый редактор и вставьте туда всю информацию (ссылки, текст, что угодно).
2. Подготовка репозитория GitHub / примеров кода 👨🏻💻
В большинстве случаев техническая статья будет включать код, команды и другие артефакты. Подготовьте полный работающий проект со всем необходимым кодом и разместите его на GitHub.
Часто читатель просто хочет прочитать код и убежать, чтобы читателю было очень легко сделать это. Репозиторий GitHub с примером проекта позволяет читателю просто взглянуть на код и пропустить английский.
3. Сначала пишите заголовки 📝
Один из самых важных шагов. Меня не волнует, будете ли вы следовать этому точному процессу или любому другому, этот шаг должен быть выполнен в любом случае. Это сильное болеутоляющее.
🚀 Определите, каковы основные заголовки статьи, и запишите их. Когда у вас есть основные заголовки, запишите подзаголовки. Под каждым заголовком напишите одну или две строчки, объясняющие, что необходимо сделать в этом заголовке.
Не пишите фактическое содержание, как бы это ни искушало вас, не начинайте писать фактическое содержание, пока вы не записали заголовки.
Уделите этому шагу столько времени, сколько захотите, цель здесь - создать скелет статьи с заголовками.
🧒🏻 В начальной стадии эта статья состояла из нескольких заголовков. Ниже вы можете увидеть, как выглядела эта статья, когда я записывал только заголовки.
4. Вставить образцы кода 💉
Под заголовками начните вставлять образцы кода, которые вы будете использовать в качестве примеров для объяснения концепции. Вставьте столько, сколько хотите, потому что код - это настоящая правда.
Убедитесь, что код отформатирован и синтаксис выделен, никто не хочет читать неформатированный и черно-белый код.
В зависимости от платформы, которую вы используете для написания блогов, у вас будет возможность отображать код.
Для средних пользователей используйте GitHub Gists для отображения примеров кода.
- Зайдите в GitHub Gists.
- Напишите код и создайте новую суть.
- Скопируйте URL-адрес gist и вставьте его в Medium. Medium автоматически загрузит суть.
Ниже показано, как выглядит суть GitHub.
Если у вас нет другого варианта для отображения отформатированного / выделенного кода, используйте Carbon.
- Перейдите в Карбон.
- Вставьте свой код.
- Выберите тему и шрифт по своему вкусу.
- Нажмите на экспорт и импортируйте экспортированное изображение в Medium.
Помните! хотя углерод может выглядеть очень красиво ✨, это изображение, читатель не сможет скопировать с него код.
Ниже приведен образец изображения, созданного с использованием углерода.
5. Добавьте английский! ☕️
На этом вы закончили более половины статьи.
Это последний важный шаг, и его следует делать в последнюю очередь.
Теперь добавьте контент на английском (или на выбранном вами языке) под заголовки, подробно объяснив заголовок и предоставив необходимые шаги. При необходимости добавьте надлежащее объяснение.
Передайте все, что вы пишете из Grammarly, на предмет грамматических ошибок.
Вы не привязаны к «процессу», но вы должны следовать ему.
Помните, что это всего лишь процесс, а не жесткое правило. Это здесь, чтобы вам было проще писать статьи.
Измените любой шаг по своему вкусу. Например, вы можете писать теоретические статьи, и шаг Вставить образцы кода не подходит. В этом случае замените его чем-то вроде Вставьте соответствующие цифры.
📢 Важно иметь процесс. Если вы не можете придумать что-то свое, просто используйте приведенный выше, пока не получите. И придерживайтесь этого!
Дополнительные точки внимания
Вот несколько дополнительных моментов в произвольном порядке, которые я учитываю при написании статьи.
1. Поток. Носите ридер руками (не буквально)
Думайте о статье, как если бы вы переносили читателя из пункта A в B, и в этом путешествии заголовки / подзаголовки этой статьи - это поезда, автомобили и автобусы, которые читатель должен выключатель. Сделайте переход от одного заголовка к другому легким для мозга читателя.
Статья должна быть одной прямой. Читателя не следует просить снова и снова переходить вверх и вниз к определенному разделу.
2. Структура и форматирование.
Правильно структурируйте свою статью, определите недостатки, такие как заголовки, которые на самом деле должны быть подзаголовками, абзацы, которые должны отображаться в виде маркированного списка.
👔 И, пожалуйста, отформатируйте правильно, никто не любит читать статьи, в которых есть случайные лишние пробелы, неформатированный код, заголовки и подзаголовки, которые выглядят одинаково.
3. Слишком много английского
Вы пишете не эссе на английском языке, это техническая статья. Сведите к минимуму использование сложных слов, ваш читатель может плохо разбираться в английском (и вы тоже).
Не пытайтесь объяснять каждую концепцию, объясняйте только те концепции, которые имеют прямое отношение к статье. Для косвенных / связанных понятий просто дайте ссылку на другую статью, веб-сайт или документацию.
4. Ссылки и справочные материалы
Добавьте как можно больше ссылок. Это не только помогает с SEO вашей статьи, но и помогает читателю. Например, ваша статья может предполагать, что читатель знает язык программирования Limbo, но это может быть не так. Так что добавляйте все больше и больше ссылок.
Конец
В конце концов, важно иметь процесс, особенно если вы планируете писать блоги, статьи и учебные пособия в будущем. Это сэкономит вам много времени, нервов и несколько клеток мозга 🧠.
А теперь ... разбейте кнопку Medium Clap и продолжайте ее нажимать !!!
Скопируйте и вставьте куда-нибудь этот контрольный список:
- Сбор информации
- Подготовьте проект GitHub / образцы кода
- Сначала пишите заголовки
- Вставьте образцы кода
- Пишите по-английски
Написано Гурлин Сетхи, вы можете найти меня в LinkedIn, Medium, GitHub.
