Руководство разработчика программного обеспечения по техническому письму
The Economist однажды разместил объявление с просьбой опубликовать статью в научной журналистике для участия в стажировке в его команде. Компания специально заявила, что лучше иметь ученого, который может писать, чем журналиста, который немного разбирается в науке.
Имея это в виду, как опытный разработчик программного обеспечения и технический писатель, вот мои советы по написанию технических статей. Я имею в виду статьи, аудиторией которых являются технические специалисты, ищущие информацию о технологическом продукте, платформе или инструменте.
Привычки и инструменты
Если вы когда-либо думали о писательстве и работаете с технологиями, вам обязательно следует подготовиться к созданию технических статей. Да, письмо улучшается только с практикой, но вам не нужно обладать каким-то мистическим писательским талантом. Во времена социальных сетей почти все пишут. И, как известно любому редактору, вовлеченность — это не совсем то же самое, что литература.
Возможно, вы захотите написать о новой технологии, которую вы только что использовали или хотите использовать, или, может быть, вы чувствуете себя обязанным продвигать одну из ваших существующих технологий.
Если вы когда-либо выступали на конференции, то понимаете, что это форма барьерного вызова. Вы решили принять это, и после того, как вы сделаете это один раз, это вопрос повторения шаблона. Написание аналогично; найдите правильные инструменты и правильные источники, а затем найдите лучшее время, чтобы добавить слова на страницу.
Поддерживать привычку сложнее. Я уверен, что вы знаете кого-то, кто начал роман, но вы, вероятно, знаете меньше людей, которые закончили его. К счастью, написание около 1000 слов далеко не так утомительно. Вы можете начать с недостаточного количества слов, а затем их станет слишком много. Перечитывание черновиков и редактирование — это хлеб с маслом для писанины. У вас есть эта пустая страница только один раз.
Оказывается, письменные принадлежности имеют значение.
В технических статьях такие вещи, как текст, смешиваются с диаграммами, изображениями и кодом. Правильно отформатировать их, а затем экспортировать в конечную платформу публикации и проверить, что формат все еще в порядке, — не всегда тривиальная задача. Я могу писать в Notion, экспортировать в Markdown, а затем вставлять в WordPress. Если вы планируете написать более одной статьи, то наладить этот процесс просто необходимо.
Быть автомобильным клаксоном
Еще одна ошибка, которую нужно обойти, заключается в том, что если вы не полностью понимаете технологию, вы не можете писать о ней. Цель большинства технических постов — быть автомобильным гудком — объявить, что то, о чем вы пишете, здесь, актуально и должно быть замечено. Вы также можете выяснить, что стоит за этой технологией, какие мысли привели к ее появлению и как она помогает людям сегодня.
Конечно, вы хотите избежать ошибок, но помните: вы автомобильный гудок, а не белая бумага. Повторное объяснение вещей своим собственным голосом также нормально.
В общем, вы действительно узнаете только то, что почти уже знали, поэтому чтение другого объяснения того же самого часто бывает весьма поучительным.
Попробуйте представить понятия, основанные на том, как вы впервые столкнулись с ними, а не только на том, как их видит Google. Поместить себя в историю более чем приемлемо — действительно, это может быть необходимый уникальный ракурс.
Введение внутренних терминов или идиом, если они на самом деле не выражают что-то без дополнительного контекста, может затруднить понимание. Например, Rails описывается как «самоуверенный» — что и правдиво, и хорошо описывает, чего ожидать в дальнейшем. Принимая во внимание, что заявление о том, что в Java есть «сборка мусора», на самом деле не помогает понять сам язык. Во что бы то ни стало покажите людям ступени вниз в подвал, но сами по ним не исчезайте.
Пример
Вот пример подхода. В рамках статьи, как бы вы объяснили основы SQL в абзаце?
Должны ли вы начать с объяснения того, что SQL — это DSL (предметно-ориентированный язык — и да, если они не очевидны, вы также должны расшифровывать аббревиатуры)? Да, потому что знание того, что вы можете делать все с помощью ограниченного набора команд, имеет определенные последствия.
Стоит ли объяснять историю Oracle? Нет, но, может быть, вы можете упомянуть, когда вы впервые работали с табличными данными, чтобы помочь установить контекст. Стоит ли вам изучать реляционные базы данных? Конечно, вам придется немного объяснить о таблицах и схемах. Как насчет «первичных и внешних ключей»? Старайтесь изначально избегать использования самого внутреннего термина; начните с таких терминов, как «относится к» или «индекс».
На схемы и списки кодов. Ясно, что таблицу очень легко визуализировать и нарисовать (именно поэтому она так широко распространена), и вы можете тривиально показать как запрос, так и таблицы, с которыми он работает:
ТАБЛИЦА наций
| Имя | Континент |
|---|---|
| Казахстан | Европа/Средняя Азия |
| Филиппины | Азия |
| Румыния | Европа |
Как спросить SQL, с какого континента происходят яблоки?
>выберите имя фрукта, страну.
континент
из фруктов, нация
где fruit.origin = нация.название и fruit.name = ‘яблоко’; +——-+———+
| имя | континент |
+——-+———+
| яблоко | Европа / Центральная Азия |
+——-+———+
1 2 3 4 5 6 7 8 10 11 |
>выбрать фрукт.название, нация.континент из фруктов, нация , где фрукт.происхождение = нация.название и фрукт.название = ‘яблоко’;
+———+———+ | имя | континент | +——-+———+ | яблоко | Европа / Центральная Азия | +——-+————————+
|
Это слабая схема и тривиальный запрос, но он указывает на цель и использование SQL, а также намекает на возможные проблемы, о которых вы можете поговорить, если это уместно. Обратите внимание, что лучше сформированная пара таблиц может не служить таким простым примером.
Кроме того, вместо того, чтобы говорить о первичных и внешних ключах, более эффективна диаграмма:
Однако обратите внимание, что нет причин ограничивать ваш пример сотрудниками, отделами и офисами! Лучше, конечно, использовать примеры, которые вам небезразличны.
Сосредоточьтесь на путешествии (и другие заключительные советы)
Вы, естественно, будете использовать риторические приемы, чтобы убедить аудиторию в своей точке зрения.
Непосредственное сравнение продуктов допустимо при сравнении соответствующих товаров, но гораздо менее полезно для просто схожих технологий. После того, как вы выбрали, вы, как правило, должны использовать технологию от начала до конца, поэтому полезнее показать полный путь пользователя. Сравнения полезны для презентаций («Акулий торнадо» — это как встреча «Челюстей» и «Твистера»), но с этого момента сосредоточьтесь на путешествии.
Мне нравится использовать веб-сайты, которые работают как песочница для технологии. Например, при рассмотрении регулярных выражений было полезно показать непосредственные примеры с regexr. Это не только облегчает объяснение — посмотрите на мой замок из песка! — это также доказывает, что технология достаточно гибкая, чтобы ее можно было выразить несколькими способами.
Размещение технологий на временной шкале (рождение, рост, возможная смерть) — это естественный способ дать контекст, но еще полезнее он для выявления меняющихся потребностей и возможных встроенных проблем. «Это было начато до облачных вычислений» неявно говорит вашей аудитории, где может лежать новое направление.
Последнее, что я бы добавил, звучит как давний жизненный совет: не бойтесь изначальной посредственности. Это может быть фатально для пилота, но вы, вероятно, не вызовете большого ужаса, если ваша первая техническая статья не приземлится должным образом.
Попробуйте хотя бы несколько раз, прежде чем делать какие-либо выводы.
Дэвид был профессиональным разработчиком программного обеспечения из Лондона в Oracle Corp. и British Telecom, а также консультантом, помогающим командам работать более гибко. Он написал книгу по дизайну пользовательского интерфейса и с тех пор пишет технические статьи…
Узнайте больше от Дэвида Истмана
Уважаемые коллеги-разработчики: запишите свои идеи | Julien Jorge
Завершая серию поведенческих моделей, которые сделают нас лучшими разработчиками, сегодня мы сосредоточимся на удовольствии от продвижения проекта и на некоторых предложениях книг и статей для чтения.
В предыдущей статье мы видели, что нам следует сохранять желание добавлять дополнительные элементы, пока мы работаем над определенной функцией, и избегать кодирования функций только потому, что мы можем. Что же нам делать со всеми этими великими идеями, когда они приходят? Как вставлять их плавно в процессе?
Это может показаться очевидным, но занесение потребностей в список невыполненных работ — лучший способ их рассмотреть и расставить по приоритетам.
Самое худшее, что мы могли бы сделать, это иметь интересную идею, выраженную только в устной форме. Не писать их — это гарантия того, что вопросы будут время от времени возвращаться, загромождая наши умы и загрязняя действительно необходимые обсуждения. Никто не хочет обсуждать новый фреймворк UT на совещании по звуковому дизайну.
Я встречал разработчиков и менеджеров проектов, которые говорили нам, что есть много вещей, которые нужно сделать. «Какие вещи?» спросили бы мы, чтобы слышать каждый раз один и тот же ответ: «Много их, я мог бы дать вам список!». На самом деле мы могли бы использовать список, но никогда его не видели. Проблема заключалась в том, что, поскольку нигде ничего не было написано, эти люди переутомились, пытаясь их запомнить. Если бы мы надавили достаточно сильно, они могли бы назвать одну или две задачи, но не больше. Они знали, что есть и другие вещи, но не могли их вспомнить и не могли сообразить, было ли это уже адресовано или нет.
Наша цель как разработчиков программного обеспечения состоит в том, чтобы преобразовать идею в полезный продукт.
Мы, конечно, не пытаемся превратить пять требований в двадцать открытых вопросов. Поэтому, когда возникает один вопрос, ошибка или потребность, мы должны с этим справиться. Мы должны представить его владельцу продукта, дать подсказку к ответу, если он у нас есть, позволить ему определить его приоритет и следовать его решению. Если идея принята, мы не должны возвращать ее для обсуждения. Если от него отказываются, мы все равно не должны его возвращать.
Дело в том, что мы не должны оставлять вопрос нерешенным; мы должны что-то с этим делать. В зависимости от времени, когда сделано замечание, может быть более эффективным сделать его немедленно, как правило, для обратной связи при проверке кода или тестировании истории. В общем случае минимум, что нужно сделать, это записать его для дальнейшего наблюдения.
Некоторые вещи все еще сложны или слишком гипотетичны, чтобы обсуждать их эффективно; в таком случае он обязательно упадет в забытые глубины отставания. Хорошо, если функция кажется нам очень важной, — материализовать ее с помощью прототипа, чтобы каждый мог судить о результатах, тем самым продвигая проект вперед.
Такое активное поведение приветствуется и за пределами области разработки программного обеспечения. У одного очень хорошего менеджера, которого я встречал, была склонность делать что-то, когда это было необходимо. Проект застрял, потому что нам нужна была обратная связь от другой компании? Он позвонит им. Адаптер отсутствовал, когда встреча началась? Он будет тем, кто встанет и найдет его. Работать с ним было одно удовольствие, потому что он был деятелем. Мы все должны быть делателями, а не рассказчиками.
Если вы прочитали все статьи этой серии, то теперь вы готовы стать лидером и надежным, точным, дотошным и целеустремленным разработчиком. Я бы посоветовал продолжить чтение некоторых книг и статей ниже, чтобы усовершенствовать свои навыки.
Выпуск DOOM под лицензией GPL помог мне понять, что я всегда могу учиться и улучшать свои навыки.
Взгляните на его файл readme: https://github.com/id-Software/DOOM
Code Complete: A Practical Handbook of Software Construction , Second Edition, Стив МакКоннелл, является обязательной к прочтению книгой для каждого программного обеспечения. разработчик. Он охватывает каждую часть разработки программного обеспечения и подкрепляет свои утверждения цифрами и очень хорошими ссылками. Это простой способ повысить уровень наших навыков. Попросите вашу компанию купить его, купите его сами или найдите друга, у которого вы можете его одолжить, а затем прочитайте его.
Чистый код: руководство по гибкому программному мастерству , Роберт С. Мартин. Это отличная книга, на очень хороших примерах объясняющая, как писать код, чтобы наши читатели и мы сами легко его понимали. Он также предоставляет набор запахов кода, чтобы помочь определить, когда что-то идет не так.
Чистый кодер: Кодекс поведения для профессиональных программистов , Роберт С. Мартин.
