Напиши первый блог: блог для программистов

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

Мой совет? Просто напиши это.

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

Но вот в чем дело. Мне тоже пришлось написать свою первую статью. Вы можете сказать, что вы не учили писать статьи, но я не училась писать программы, но я здесь!

Если я сейчас прочитаю свою первую статью о try-catch-finally в Visual Basic .Net, я не могу не смеяться над ее простотой. Я занимался программированием около четырех месяцев, мой работодатель решил, что некоторые сотрудники должны были пройти обучение, и поэтому кто-то подошел и научил нас основам .NET, одним из которых был блок try-catch-finally.

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

И поэтому я слышу, как вы говорите, что в конечном итоге я был обучен темам, о которых я писал, в то время как вы все еще не научились писать статьи. Давайте поговорим о моей второй статье.

Вы можете прочитать это, но не можете. Никто не может. Это было плохо. Так плохо, что он не был принят в CodeProject, и я вообще удалил его.

Тем не менее, эта статья по-прежнему лучшая статья, которую я когда-либо писал. Не потому, что статья была такой хорошей, очевидно, а потому, что нет ни одной статьи или даже книги, которая бы научила меня больше, чем эта статья. Статья была о некоторых концепциях объектно-ориентированного программирования (ООП), которые могут показаться интересными, за исключением того, что я не знал, что такое объектно-ориентированное программирование.

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

Я не позволил этому сбить меня с толку.

Я проглотил свою гордость, любезно поблагодарив рецензентов за их отзывы и спросив, могут ли они направить меня, чтобы я мог улучшиться. В конечном итоге я узнал о ООП, ТВЕРДЫХ и шаблонах проектирования.

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

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

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

Мой ответ: Лично мне нравится писать так, как будто я разговариваю с читателем. Я использую такие слова, как «я», «вы» и «мы», в надежде, что это привлечет внимание читателей.

Помимо этого, я стараюсь привлекать людей, задавая вопросы. Звучит сложно, правда? Ну, это действительно не так. (Видите, что я там делал?) Многим нравится мой стиль письма, но у меня также были жалобы на то, что мой стиль слишком неформален, из-за чего ему трудно следовать.

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

Моя первая мысль — да, конечно, это нужно делать, но что мне делать? Лично я не фанат «одного», но если вам удобнее пользоваться им, не позволяйте мне вас сдерживать. Это может занять несколько статей, чтобы найти свой собственный стиль. В конце статьи важно только одно: узнала ли моя аудитория что-нибудь?

Если бы люди хотели читать хорошо написанную литературу, они бы не читали технические блоги, кроме Шекспира (или чего бы то ни было). Конечно, ваш блог будет читаться намного лучше, если он будет грамматически корректным, если ваш стиль соответствует предпочтениям читателя, и если он в целом высокого качества, но это все довольно субъективно и часто не нарушает договоренности.

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

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

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

К тому времени, как вы прочтете эту статью, по крайней мере три человека прочтут ее: корректор, который проверяет орфографию, грамматику и все ли в стиле простого программиста; редактор контента, который проверяет контент, поток и корректность; возможно, тот, кто проверяет технологический

Структура паттерна модель-вид-контроллер [источник: Википедия].

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

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

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

Также убедитесь, что у вас есть права на использование изображений. Либо они ваши, либо у вас есть разрешение на использование фотографий и указание источника.

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

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

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

Объясняя все
Вот что мне нравится делать: объяснять все, что делает мой код. Это звучит как открытая дверь, но на самом деле это не так.

Если есть что-то, что читатель не может знать, я упоминаю об этом. Например, я говорю о Entity Framework, а в моем примере показано свойство:

public virtual ICollection<MyEntity> { get; set; }

view rawVirtualICollection.cs hosted with ❤ by GitHub

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

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

Еще одним интересным фактом является то, что реализация ICollection, Collection, не является широко используемым типом коллекции, потому что она находится не в пространстве имен System.Collections.Generic, а в пространстве имен System.Collections.ObjectModel (из-за некоторого конфликта имен со старым Тип Visual Basic Collection). Из-за этого редко можно увидеть интерфейс ICollection вообще.

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

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

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

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

Как я уже сказал, ваша аудитория, вероятно, читает ваш блог, чтобы чему-то научиться. Возможно, вы написали о Entity Framework или LINQ, и читатель пытается лучше понять предмет. Если ваш пост — это статья для начинающих, очень важно, чтобы вы как можно более подробно объяснили и чтобы ваши примеры были простыми и создавали трудности в конце статьи.

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

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

Примеры кода

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

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

Когда я пишу статью, я ожидаю, что моя аудитория будет студентом. Например:

if (SomeFunction())
{

view rawSingleline.cs hosted with ❤ by GitHub

Будет написано как:

// We need the result of SomeFunction
// before we can continue.
bool result = SomeFunction();
if (result)
{

view rawExpanded.cs hosted with ❤ by GitHub

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

Помимо легкости отслеживания, ваш код должен быть хорошо отформатирован. Хотя ваша среда IDE, как и Visual Studio, довольно хорошо форматирует код, страница блога обычно не очень хороша. Блоги часто имеют относительно небольшую ширину, зарезервированную для текста, поэтому более длинные строки кода будут обрезаны посередине. В зависимости от вашего CSS, ваш код будет выходить за границы страницы или переходить к следующей строке.

Есть несколько плагинов WordPress, которые могут отформатировать ваш код. Если вы пишете для другого веб-сайта, такого как Simple Programmer, который использует GitHub Gists для примеров кода или CodeProject, подсветка синтаксиса может быть включена, а может и не включена, а может и не соответствовать тому, к чему вы привыкли.

Когда вы пишете книгу, ваш код должен умещаться на странице и печататься в черно-белом варианте, поэтому лучше, чтобы строки кода были короткими и удобочитаемыми. Например:

var result = people
    .Where(x => x.Name.StartsWith("A"))
    .OrderBy(x => x.Name)
    .ToList();

Вместо:

var result = people.Where(x => x.Name.StartsWith("A")).OrderBy(x => x.Name).ToList();

Но вот еще лучшая альтернатива (которую я уже использовал до этого момента):

var result = people
.Where(x => x.Name.StartsWith(«A»))
.OrderBy(x => x.Name)
.ToList();

Это три части одного и того же кода, один неформатированный, один

отформатированный и один отформатированный с использованием стороннего средства форматирования кода (GitHub Gist). Я предполагаю, что вы предпочитаете GitHub Gist для читабельности, даже если это тот же код, что и в предыдущем примере.

Трудные части написания сообщений в блоге
Написание поста в блоге не так уж сложно, если вы знаете, о чем писать. Для меня самые сложные части — это всегда придумывать тему, создавать пример проекта (если применимо) и писать первое и последнее предложение.

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

Открытие предложений

Темы и образцы на ваше усмотрение. Я могу немного помочь с первым и последним предложением, хотя. Хороший стартер может быть: «В этой статье я хочу обсудить…» или, если вы делаете серию, «В моем последнем посте мы говорили о… [в прошлой теме]. В этом посте я хочу рассказать о … [новой теме] ».

Или вы можете начать с того, что заставило вас написать конкретный пост. В этом случае меня спросили, как написать пост в блоге как программиста, поэтому я решил написать пост в блоге (перечитайте главное предложение). К другим личным примерам относятся: «Я сейчас готовлюсь к экзамену…» и «Более года назад […] я был свидетелем лекции…»

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

Вы также можете «просто начать». Моя первая статья началась с «Обработка ошибок — важная часть разработки программного обеспечения…». Другая началась с «.NET Framework предоставляет коллекции различных типов…». Преимуществом этого подхода является то, что он понятен о чем будет ваш пост и почему каждый должен прочитать его с самого начала.

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

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

Например: «Ну вот и все! Я, конечно, многому научился, записав это. Я буду рад ответить на любые вопросы в комментариях ». Это немного дружелюбнее, чем просто внезапно остановиться.

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

Если вы объясните фрагмент кода и потратите 500 слов на одну деталь, было бы странно обсуждать еще одну, не менее важную деталь, всего за 20 слов. Точно так же было бы странно, если бы вы потратили 500 слов на неважную деталь, когда, может быть, достаточно кратко упомянуть об этом.

Вы также можете так много сказать. Для своих сообщений в блоге я обычно сохраняю диапазон от 2000 до 3000 слов. Я планирую обсудить пару концепций, скажем, четыре, поэтому у меня есть около 500 слов на концепцию. Может быть, мне понадобится 400 слов для одной концепции и 600 для другой, но я, вероятно, не могу использовать 1000 для одной концепции. Может быть, вы хотите подробно обсудить эти четыре понятия, а затем упомянуть еще два или три понятия, чтобы подтолкнуть читателя к дальнейшему изучению; это действительно зависит от вас.

Например, я написал сообщение в блоге о NoSQL и MongoDB. Я потратил около трети на NoSQL в целом и две трети на MongoDB. Я потратил один абзац на установку MongoDB, и я упоминаю, что вы можете делать все что угодно из командной строки, но я собираюсь перейти непосредственно к C # коду для этой статьи. Мы рассмотрим основы CRUD, но я также быстро упомяну, что вы можете вставить полные списки.

Для этой статьи я решил написать ее, так что этого достаточно, чтобы начать, но недостаточно, чтобы быть опытным. Это выбор, но вы должны сделать это заранее, прежде чем начнете писать слишком много.

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

Теперь приступим к письму
Теперь это зависит от вас! Сделайте блог, или, может быть, у вас уже есть, или найдите сайт, где вы можете написать свои собственные статьи.

Есть много ресурсов в Интернете, чтобы начать. Есть даже бесплатный курс по Simple Programmer, который поможет вам создать свой блог. Таким образом, у вас действительно нет никаких оправданий, чтобы не писать!

И как только вы начнете писать, продолжайте в том же духе!

Я буду рад ответить на любые вопросы в комментариях.

Удачи!

Интернет по оптике в Миассе AirNet