Как вести технический блог
Все про Блоггинг

Как вести технический блог

Краткое резюме

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

вступление

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

Состав технического поста

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

Позвольте мне объяснить, что это такое.

Заголовок

Заголовок в техническом посте очень важен. Это часть содержания, которая говорит читателю, как что-то делать. Вот почему многие технические заголовки используют подход «как делать X». Он ясен, прямолинеен и не содержит какой-либо запутанной терминологии (последнее, что вы хотите сделать, это запутать своих читателей). Если вы не заметили, заголовок этого поста является реализацией этого подхода.

Другими очень полезными типами заголовков являются следующие:

Writing a $technology $thing.

Developing with $technology.

Testing $technology with $thing.

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

Краткое резюме

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

Требования

Требования — это то, что необходимо читателям, чтобы успешно прочитать и применить то, что охватывает публикация. Если вы пишете учебник по Python, то требования будут следующими: используемая версия Python, текстовый редактор и т. Д. Будьте очень конкретны и по возможности включайте версии. Позвольте мне использовать приведенный выше пример, чтобы показать вам, как это делается:

Требования:

Python 3.6.1

Text Editor (Vim was used for the examples)

Operating System (Linux, MacOS, Windows) with version information (Ubuntu 16, MacOS 10.12, Windows 10 Professional)

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

Вступление

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

Python has become the defacto glue language in software development. In it's newest version (3.6.1), the language has evolved into a powerful tool that is easy to pick up. Python is included as a default in most Linux distros, and in MacOS. Such widespread adoption means you will probably not need to install anything in order to run Python on your machine. Follow along as I explain how to use Python's F-Strings in a Linux environment.

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

Многоступенчатое объяснение

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

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

Объем в технических постах то же, что и в языках программирования. У вас есть местный и Глобальный объем. Глобальный охват означает, что информация, обсуждаемая в каком-то месте, применима ко всему остальному. Локальный охват означает, что обсуждаемая информация относится ко всему, что вы сейчас читаете.

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

Есть несколько способов локально инкапсулировать область видимости с помощью визуальных подсказок. Визуальные подсказки — это графические или типографические элементы, которые позволяют вам сообщить читателю, что все в определенной области тесно связано с самим собой (локальная область действия), но не очень связано с глобальной областью. Позвольте мне показать вам пример:

#######
#
# This is a globally encapsulated scope. 
# Note that everything that I write here is assumed to be directly related.
# 
# I wrote this post as a result of a Tweet!
#
######


######
#
# This is a locally encapsulated scope. What I write here is separate from the rest.
#
#  #####
#  #
#  # How are you enjoying this post?
#  #
#  #
#  # #####
#  # #
#  # # Yes, this totally looks like OOP. It is not a coincidence. :)
#  # #
#  # #####
#  # 
#  #####
#
######

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

  • Во-первых -> Да, это полностью похоже на ООП. Это не совпадение. 🙂
  • Второй -> Как вам нравится этот пост?
  • Третий -> Это локально инкапсулированная область видимости. То, что я пишу здесь, отдельно от всего остального.

Таким образом, разбейте все на более мелкие шаги и предоставьте визуальные подсказки, которые информируют читателя об объеме. Сохраните то, что локально связано с конкретным шагом. Если вы сомневаетесь, разбейте все и дайте визуальные подсказки. Лучше иметь несколько маленьких (микро) шагов, чем несколько больших.

Примеры

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

Примеры — самая важная часть технического сообщения, потому что люди будут использовать их, чтобы понять, что вы обсуждаете. Фактически, то, как люди реагируют на технический пост, напрямую зависит от того, насколько хорош предоставленный пример. Чем больше примеров вы приведете, тем лучше. Однако не забудьте предоставить примеры разной длины и типа. Вы не хотите забыть включить пример «Hello, World», но вы также не хотите, чтобы он был единственным примером, который вы включаете. Позвольте мне показать вам несколько примеров, из которых вы можете извлечь пользу, используя F-строки Python.

Очень простой пример, используемый в качестве введения:

# python 3.6.1 on MacOS 10.12

# Hello world with F-Strings

name = "World"
print(f"Hello, {name}")

Простой пример, демонстрирующий некоторые конкретные технические детали (локальный объем):

# python 3.6.1 on MacOS 10.12

# Using Python's F-Strings in functions

def hello(name):
    return f"Hello, {name}"

def print_hello(name):
    print(hello(name))

Более сложный пример:

# python 3.6.1 on MacOS 10.12

# Implementing FizzBuzz with Python's F-Strings
# and ternary operators

def fizzbuzz():
  for i in range(1, 101):
      print(f"FizzBuzz with number {i}") if i % 3 == 0 and i % 5 == 0 else None
      print(f"Fizz with number {i}") if i % 3 == 0 else None
      print(f"Buzz with number {i}") if i % 5 == 0 else None
      print(f"Now on number {i}")

Дело в том, чтобы повысить сложность примеров, чтобы направить пользователя в его учебном путешествии. Каждый из приведенных выше примеров основан на последнем и имеет одну основную тему: F-строки Python.

подсказки

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

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

  2. Избегайте использования низкоконтрастных цветов для визуальных подсказок. Светло-серый шрифт на темно-сером фоне не очень хорош. Сделайте это легко читаемым.

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

  4. ЦЕЛОВАТЬ. Держать его просто глупо. Не включайте лавину подробностей, если подойдет небольшая горстка.

  5. Изучите высоко оцененные технические сообщения или документацию. Люди любят хвалить документацию Stripe. Выясните, почему и примените то, что вы узнали, к своему посту.

  6. Используйте графику, чтобы разбить текст. Обычно я стараюсь использовать как можно меньше графики, но они могут быть полезны. Это зависит от того, что обсуждается. В большинстве случаев вам придется рисовать собственную графику. Не делайте их слишком красочными. Придерживайтесь 2-5 цветов и делайте их простыми.

  7. Не помещайте исходный код в графику или изображения. Люди хотят скопировать и вставить код в свои редакторы.

  8. Разрешите им запустить код в самой статье. Это не всегда возможно, но в таких случаях полезно.

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

  10. Лучше всего светлый тон. Юмор не помогает. Держите шутки подальше от исходного кода.

Резюме

Резюме — это место, где можно добавить ссылки на дополнительную информацию, поблагодарить тех, кто помогал написать сообщение, и добавить все, что может быть полезно читателю. Мне нравится использовать следующий формат:

You have now learned about Python's F-Strings. If you'd like to learn more about them, please visit the following links:

- Pep 498, https://www.python.org/dev/peps/pep-0498/

I must thank all of the people who made this post possible. If you need Python development services, please visit yelluw.com and use the contact form to get in touch with me. Feel free to email me at [email protected] with questions.

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


Теперь вы научились писать технические сообщения в блогах. Это очень полезно знать, потому что компании, как правило, нанимают разработчиков программного обеспечения, которые могут общаться
четко. Это также может быть способом увеличения вашего дохода. Я должен поблагодарить Стефани Херлбурт за идею и поддержку. Следуйте за ней в Twitter @sehurlburt потому что она классная.

Если вам нужно написать для вас технические сообщения, не стесняйтесь обращаться ко мне через веб-сайт Yelluw. Вы также можете написать мне на [email protected] Вам также следует подписаться на аккаунт Yelluw в Twitter. @yelluwmedia и мой личный кабинет @pryelluw. Я также могу заключить краткосрочные и долгосрочные контракты на разработку программного обеспечения. Сейчас я сосредоточен на Python, Django и Javascript.

Вам также может понравиться...

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *