Технічний текст для розробників

HTML, CSS, JavaScript, Python, PHP, C++, Dart — існує так багато мов програмування, і ви навіть можете абсолютно вільно володіти кількома з них! Але оскільки ми прагнемо писати більше та кращий код, те, як ми пишемо та спілкуємося повсякденною мовою, стає дедалі важливішим… і, можливо, навіть не помічається.

Те, як ми пишемо про код і навколо нього, мабуть, таке ж важливе, як і сам код. І незважаючи на те, де ви потрапили в цю лінію, ми всі можемо погодитися, що наші слова мають потенціал як допомогти, так і зашкодити ефективності коду.

У цій статті я хочу окреслити, як ці дві, здавалося б, різні сфери — програмування та написання — можуть поєднатися й підняти наші навички розробника на наступний рівень.

Зачекайте, технічний запис? Так, саме це я маю на увазі. Я щиро вірю, що ми всі в тому чи іншому сенсі письменники. І я тут, щоб дати вам посібник із порадами щодо написання, порадами та прикладами того, як це може зробити вас кращим розробником і комунікатором.

Технічне письмо всюди

Минулого року команда популярного клієнта Mac Git, Tower, опитали понад 4,000 розробників і виявили, що майже 50% із них витрачали 3-6 годин на день на написання коду.

І так, це одне опитування досить вузької групи, але я думаю, що багато хто з нас потрапляє десь у цей діапазон. У будь-якому випадку, розробник не пише код 24/7, оскільки, як показує це опитування, ми витрачаємо багато часу на інші справи.

Це може включати:

• демонстрація нової функції,
• документування цієї нової функції,
• оновлення робочого квитка, пов’язаного з цією новою функцією, або
• резервна робота для підтримки цієї нової функції.

Звичайно, завжди є час для перерв у туалеті та Wordle.

У будь-якому випадку більшість речей, які ми зазвичай робимо, включають спілкування з такими людьми, як ваша команда, колеги, клієнти, користувачі та інші розробники.

Отже, ми витрачаємо значну частину нашого часу на спілкування з людьми слова на додаток до зв’язку, який ми маємо з комп’ютерами код. Слова — це письмова мова. І якби ми краще писали свої слова, ми б краще спілкувалися. Коли ми спілкуємося краще, ми з більшою ймовірністю отримаємо те, чого хочемо.

Це Technical Writing 101.

І це навіть не закінчується. Деякі програмісти також люблять створювати власні продукти, а це означає, що їм потрібно зробити маркетинг частиною своєї роботи. Технічне письмо також відіграє величезну роль у цьому. Отже, так. Я вважаю, що досить справедливо сказати, що технічне письмо є дійсно скрізь

Що таке хороша граматика?

З такою кількістю мов програмування, останнє, що ми хочемо, це вивчити ще одну.

Граматика є невід’ємною частиною англійської мови, і вона розкриває весь потенціал спілкування. Це робить нас більш формальними, професійними та послідовними.

Дозвольте коротко описати мову.

Англійський синтаксис

Як і мови програмування, англійська має чітко визначений синтаксис, і він починається зі слів.

Слова є будівельними блоками англійської мови, і вони поділяються на вісім груп:

Подумайте про них як UI компоненти: це модульні частини, які можна переміщати, щоб побудувати повне та міцне речення, так само, як ви можете зібрати повне та надійне UI. Чи всі компоненти повинні бути там постійно? Звісно ні! Зберіть речення з частин, необхідних для завершення досвіду, так само, як і з інтерфейсом.

Голос і тон

Лексика, пунктуація, будова речення та вибір слів. Це все складові англійської мови. Ми використовуємо їх, щоб ділитися ідеями, спілкуватися з друзями та сім’єю та надсилати електронні листи нашим колегам.

Але вкрай важливо враховувати звук наших повідомлень. Дивно, як один знак оклику може повністю змінити тон повідомлення:

1. Я люблю програмувати.
2. I як програмування! :)

Голос легко сплутати з тоном, і навпаки.

Голос це те, що стосується нашого вибору слів, який залежить від контексту. Наприклад, підручник для початківців, швидше за все, використовує сленг і неформальну мову, щоб передати дружній голос, тоді як документація може бути написана офіційно, серйозно та професійно, намагаючись перейти прямо до суті.

Те саме повідомлення, написане двома різними голосами:

• Весело: «Розширюйте свою соціальну мережу та будьте в курсі того, що зараз актуально».
• Серйозно: «Знайдіть роботу в одній із найбільших програм соціальних мереж та онлайн-ринку вакансій».

Нерідко випадково писати повідомлення, які виглядають як поблажливі, образливі та непрофесійні. Ось де тон вступає в гру. Читайте свої повідомлення вголос, змусьте інших людей прочитати їх за вас і поекспериментуйте зі своєю пунктуацією та структурою речень. Так ви відточуєте свій тон.

Ось інший спосіб подумати про це: ваш голос ніколи не змінюється, але ваш тон змінюється. Ваш голос схожий на те, ким ви є як особистість, тоді як тон — це те, як ви реагуєте в певній ситуації.

Активний і пасивний стан

У реченні завжди є діяч, дієслово та мета. Порядок, у якому вони йдуть, визначає, чи буде речення написано в активному чи пасивному стані.

Актор виступає на першому місці активний голос. Наприклад: «CSS малює фон».

Речення, у яких використовується активний голос, більш зрозумілі, ніж відповідники. Вони чіткіші, коротші та зрозуміліші — ідеально підходять для більш професійного голосу, який переходить прямо до суті.

З пасивний стан, актор приходить останнім. (Бачите, що я там зробив?) Це означає, що наш актор — у цьому випадку CSS — приходить у кінці так: «Тло намальовано CSS».

Читачі зазвичай перетворюють пасивний стан на активний у своїй голові, що призводить до збільшення часу обробки. Якщо ви коли-небудь чули, що краще писати активним голосом, зазвичай це причина. Технічні автори здебільшого віддають перевагу активному голосу, за дуже невеликими винятками, як-от посилання на дослідження: «Було припущено, що…»

Але це не означає, що ви завжди повинні прагнути до активного голосу. Перемикання з одного речення на інше — навіть у тому самому абзаці — може зробити ваш вміст більш плавним, якщо використовувати його ефективно.

Уникнення помилок

Граматика полягає в структурі та правильності мови, і немає нічого кращого для досягнення цього, ніж швидка перевірка вашого документа. Дуже важливо позбавити свої твори від орфографічних помилок, граматичних проблем і семантичних недосконалостей.

Наприкінці цієї статті я покажу вам безцінні інструменти, якими користуються професіонали, щоб уникнути письмових помилок. Очевидно, що сьогодні вбудовані засоби перевірки орфографії є ​​майже у всьому; наші редактори коду навіть мають плагіни перевірки орфографії та linting, які допомагають запобігти помилкам. 

Але якщо ви шукаєте універсальний інструмент для граматики, Граматично є одним із найпоширеніших інструментів. Я не отримаю відкату за це чи щось інше. Це просто чудовий інструмент, який багато редакторів і авторів використовують для написання чистого та зрозумілого вмісту — подібно до того, як ви можете використовувати Emmet, eslint або будь-який інший лінтер для написання чистого та зрозумілого коду.

Написання коментарів до коду

Те, що ми пишемо для інших розробників, може мати великий вплив на загальну якість нашої роботи, незалежно від того, що ми пишемо в коді, як ми пояснюємо код або як ми надаємо відгук про частину коду.

Цікаво, що кожна мова програмування має стандартний набір функцій для написання коментаря. Вони повинні пояснити, що робить код. Під цим я не маю на увазі розпливчасті коментарі на зразок цього:

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

Натомість використовуйте коментарі, які надають більше інформації:

red *= 1.2 // Apply a 'reddish' effect to the image

Вся справа в контексті. «Яку програму я будую?» це саме те питання, яке ви повинні собі поставити.

Коментарі мають додати цінності

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

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

Пам’ятайте, що мета коментаря – додати цінність фрагменту коду, а не повторити його. Якщо ви не можете цього зробити, краще просто залишити код як є. Що робить ці приклади «лінивими», так це те, що вони просто повторюють те, що, очевидно, робить код. У цьому випадку коментарі зайві, оскільки вони говорять нам те, що ми вже знаємо — вони не додають цінності!

Коментарі мають відображати поточний код

Застарілі коментарі – не рідкість у великих проектах; смію я сказати в найбільш проектів.

Давайте уявімо Девіда, програміста та всебічного крутого хлопця, з яким можна погуляти. Девід хоче відсортувати список рядків за алфавітом від А до Я, тому він робить очевидне в JavaScript:

cities = sortWords(cities) // sort cities from A to Z

Потім Девід розуміє, що sortWords() насправді сортує списки від Z до A. Це не проблема, оскільки він може просто змінити результат:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

На жаль, Девід не оновив свій коментар до коду.

А тепер уявіть, що я не розповідав вам цю історію, а ви бачили лише код вище. Можна подумати, що після запуску другого рядка коду «міста» будуть відсортовані від Я до А! Вся ця плутанина була спричинена застарілим коментарем.

Хоча це може бути перебільшеним прикладом, щось подібне може (і часто трапляється) статися, якщо ви змагаєтеся з близьким терміном. На щастя, цьому можна запобігти, дотримуючись одного простого правила... змініть свої коментарі одночасно зі зміною коду.

Це просте правило, яке вбереже вас і вашу команду від багатьох технічна заборгованість.

Тепер, коли ми знаємо, як виглядають погано написані коментарі, давайте розглянемо кілька хороших прикладів.

Коментарі повинні пояснювати однодіомний код

Іноді natuurlijk спосіб робити речі неправильний. Програмістам, можливо, доведеться трохи «порушити» стандарти, але коли вони це зроблять, бажано залишити невеликий коментар, пояснюючи їх обґрунтування:

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

Це корисно, правда? Якщо ви відповідальні за перегляд цього коду, можливо, у вас виникла спокуса виправити його без того коментаря, який пояснює, в чому справа.

Коментарі можуть визначити майбутні завдання

Ще одна корисна річ, яку можна зробити з коментарями, — це визнати, що є ще багато роботи.

// TODO: use a more efficient algorithm
linearSort(ids)

Таким чином ви зможете зосередитися на своєму потоці. Пізніше ви (або хтось інший) можете повернутися та виправити це.

Коментарі можуть посилатися на джерело

Отже, ви щойно знайшли рішення своєї проблеми на StackOverflow. Після копіювання цього коду іноді корисно зберегти посилання на відповідь, яка вам допомогла, щоб ви могли повернутися до неї для подальшого використання.

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

Це важливо, оскільки рішення можуть змінюватися. Завжди корисно знати, звідки взявся ваш код, на випадок, якщо він колись зламається.

Написання тягових запитів

Запити на витягування (PRs) є фундаментальним аспектом будь-якого проекту. Вони лежать в основі перевірки коду. А перевірка коду може швидко стати вузьким місцем у продуктивності вашої команди без хорошого формулювання.

Добрий PR опис підсумовує що вноситься зміна і чому це робиться. Великі проекти мають шаблон запиту на отримання, як цей, адаптований з a реальний приклад:

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

Уникайте невизначеності PR назви

Уникайте назв, які виглядають так:

• Виправити збірку.
• Виправити помилку.
• Додати патч.

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

PR назви традиційно пишуться наказовий спосіб. Вони є одним рядком підсумку всього PR, і вони повинні описати що виконується PR.

Ось кілька гарних прикладів:

• Підтримка спеціальних атрибутів srcset у NgOptimizedImage
• Стандартна конфігурація зображення для 75% якості зображення
• Додайте явні селектори для всіх вбудованих ControlValueAccessors

Уникайте довгих PRs

Великий PR означає величезний опис, і ніхто не хоче переглядати сотні чи тисячі рядків коду, іноді просто для того, щоб у підсумку відкинути все!

Замість цього ви можете:

• спілкуватися зі своєю командою через Питання,
• скласти план,
• розбити проблему на менші частини, або
• працювати над кожним твором окремо зі своїм PR.

Хіба тепер не набагато чистіше?

Надайте деталі в PR тіло

На відміну від PR назва, тіло є місце для всіх деталей, включаючи:

• Чому саме PR робиться?
• Чому це найкращий підхід?
• Будь-які недоліки підходу та ідеї щодо їх вирішення, якщо можливо
• Номер помилки або квитка, результати тестування тощо.

Повідомлення про помилки

Звіти про помилки є одним із найважливіших аспектів будь-якого проекту. І всі великі проекти будуються на відгуках користувачів. Зазвичай, навіть після незліченних тестів, саме користувачі знаходять більшість помилок. Користувачі також великі ідеалісти, і іноді у них є ідеї щодо особливостей; будь ласка, послухайте їх!

Для технічних проектів усі ці речі виконуються шляхом звітування про проблеми. Іншому розробнику легко знайти та відповісти на добре написану проблему.

Наприклад, більшість великих проектів йдуть разом шаблон:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

Зберіть скріншоти

Зафіксуйте проблему за допомогою свого утиліта для зйомки екрана системи.

Якщо це скріншот a CLI програмі переконайтеся, що текст чіткий. Якщо це a UI переконайтеся, що на знімку екрана зображено правильні елементи та стани.

Можливо, вам знадобиться зафіксувати реальну взаємодію, щоб продемонструвати проблему. Якщо це так, спробуйте записувати GIF-файли за допомогою інструменту запису екрана.

Як відтворити проблему

Програмістам набагато легше усунути помилку, коли вона живе на їх комп’ютері. Ось чому хороший комміт має супроводжуватися кроками для точного відтворення проблеми.

Ось приклад:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

Запропонуйте причину

Ви виявили помилку, тож, можливо, ви можете запропонувати деякі можливі причини її появи. Можливо, помилка виникає лише після того, як ви зіткнулися з певною подією, або, можливо, вона трапляється лише на мобільному пристрої.

Також не завадить вивчити кодову базу та, можливо, визначити, що спричиняє проблему. Тоді вашу проблему буде закрито набагато швидше, і вас, ймовірно, буде призначено до пов’язаних PR.

Спілкування з клієнтами

Ви можете працювати самостійним фрілансером або бути провідним розробником у невеликій команді. У будь-якому випадку, скажімо, ви відповідаєте за взаємодію з клієнтами в проекті. 

Стереотип програміста полягає в тому, що ми погані комунікатори. Відомо, що ми використовуємо надто технічний жаргон, розповідаємо іншим, що можна, а що ні, і навіть захищаємося, коли хтось ставить під сумнів наш підхід.

Отже, як нам пом’якшити цей стереотип? Запитуйте клієнтів, чого вони хочуть, і завжди прислухайтеся до їхніх відгуків. Ось як це зробити.

Задайте правильні запитання

Почніть із того, що переконайтеся, що ви та клієнт перебуваєте на одній сторінці:

• Хто ваша цільова аудиторія?
• Яка мета сайту?
• Хто ваш найближчий конкурент і що вони роблять правильно?

Запитання також є хорошим способом писати позитивно, особливо в ситуаціях, коли ви не згодні з відгуком або рішенням клієнта. Ставлячи запитання, ви змушуєте цю людину підтримувати свої власні претензії, а не атакуєте її, захищаючи свою позицію:

• Ви згодні з цим, навіть якщо це супроводжується додатковими витратами на продуктивність?
• Чи допомагає переміщення компонента краще досягати нашої мети?
• Чудово, хто відповідає за його підтримку після запуску? 
• Чи знаєте ви з рук, чи відповідає контраст між цими двома кольорами стандартам WCAG AA?

Питання набагато невинніші та сприяють цікавості, а не ворожості.

Продайте себе

Якщо ви робите презентацію для потенційного клієнта, вам потрібно буде переконати їх найняти вас. Чому клієнт повинен обрати саме вас? Важливо вказати наступне:

• Хто ти
• Що ви робите
• Чому ви добре підходить для роботи
• Посилання на відповідну роботу, яку ви виконали

І як тільки ви отримаєте роботу і вам потрібно буде написати контракт, пам’ятайте, що немає більш страшного контенту, ніж купа юридичних текстів. Незважаючи на те, що він написаний для дизайн-проектів, Контрактний вбивця може бути гарною відправною точкою для написання чогось набагато дружнішого.

Ваша увага до деталей може бути різницею між вами та іншим розробником, який намагається виграти той самий проект. З мого досвіду, клієнти так само легко наймуть розробника, з яким, на їхню думку, їм сподобається працювати, аніж технічно найбільш компетентного чи досвідченого для цієї роботи.

Написання мікрокопії

Мікрокопія це мистецтво писати зручним для користувача UI повідомлення, наприклад помилки. Б’юся об заклад, що вам, як розробнику, доводилося писати повідомлення про помилки, тому що вони залишалися на задньому плані до моменту запуску.

Можливо, тому ми іноді бачимо такі помилки:

Error: Unexpected input (Code 693)

Помилки – це остання річ, з якою ви хочете мати справу з вашими користувачами. Але вони трапляються, і ми нічого не можемо з цим вдіяти. Ось кілька порад, як покращити свої навички мікрокопіювання.

Уникайте технічного жаргону

Більшість людей не знають, що таке сервер, а 100% програмістів знають. Ось чому нерідко бачити незвичайні терміни, написані в повідомленні про помилку, наприклад API або «тайм-аут виконання».

Якщо ви не маєте справу з технічним клієнтом або базою користувачів, імовірно, що більшість ваших користувачів не проходили курс інформатики та не знають, як працює Інтернет і чому певна річ не працює. Отже, помилка.

Тому хороше повідомлення про помилку не повинно пояснювати чому щось пішло не так, тому що такі пояснення можуть вимагати використання страшних технічних термінів. Тому дуже важливо уникати використання технічного жаргону.

Ніколи не звинувачуйте користувача

Уявіть собі: я намагаюся увійти на вашу платформу. Тож я відкриваю свій браузер, відвідую ваш веб-сайт і вводжу свої дані. Потім мені кажуть: «Ваша електронна адреса/пароль неправильні».

Навіть якщо думати, що це повідомлення є ворожим, здається драматичним, воно підсвідомо змушує мене почуватися дурним. Microcopy каже, що ніколи не можна звинувачувати користувача. Спробуйте змінити своє повідомлення на щось менш відверте, наприклад цей приклад, адаптований з облікового запису Mailchimp: «Вибачте, ця комбінація електронної пошти та пароля неправильна. Ми можемо допомогти вам відновити обліковий запис».

Я також хотів би додати, що важливо уникати ВСІХ ВЕЛИКИХ БУКВ і знаків оклику! Звичайно, їх можна використовувати для передачі хвилювання, але в мікрокопії вони створюють відчуття ворожості до користувача.

Не перевантажуйте користувача

Використання гумору у вашій мікрокопії – гарна ідея! Це може покращити настрій і це простий спосіб приборкати негатив, спричинений навіть найгіршими помилками.

Але якщо ви не використовуєте його відмінно, це може здатися користувачеві поблажливим і образливим. Це просто a великий ризикувати.

Mailchimp добре каже:

Не жартуйте — вимушений гумор може бути гіршим, ніж його відсутність. Якщо ви не впевнені, зберігайте прямий вигляд.

(Наголос мій)

Написання доступної розмітки

Ми могли б легко витратити цілу статтю про доступність і те, як вона пов’язана з технічним написанням. До біса, доступність часто входить до посібників зі стилю вмісту, зокрема для Microsoft та Mailchimp.

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

Отже, якщо ви впроваджуєте чужий копірайтинг у свій код, пишете документацію для інших розробників або навіть пишете UI копіюйте себе, пам’ятайте про деякі фундаментальні найкращі практики доступності, оскільки вони завершують усі інші поради щодо технічного написання.

Такі речі:

Енді Белл пропонує деякі відносно маленькі речі, які ви можете зробити, щоб зробити вміст доступнішим, і це варте вашого часу, щоб перевірити їх. І просто так, Джон Рі демонструє кілька хитрих прийомів редагування які можливі, коли ми працюємо із семантичними елементами HTML.

Висновок

Це були шість способів, які демонструють, як технічний текст і розробка збігаються. Хоча ці приклади й поради можуть бути не науковими, я сподіваюся, що вони були для вас корисними, незалежно від того, чи це співпраця з іншими розробниками, підтримка власної роботи, необхідність написання власної копії в крайньому випадку чи навіть складання проектної пропозиції, серед іншого речі.

Підсумок: вдосконалення ваших навичок письма та докладання трохи додаткових зусиль у написанні може зробити вас кращим розробником.

Технічні письмові ресурси

Якщо ви зацікавлені в технічному написанні:

Якщо вас цікавить копірайтинг:

Якщо вас цікавить мікрокопія:

Якщо ви зацікавлені у використанні професійного посібника зі стилю, щоб покращити свій текст:

Якщо ви зацікавлені в написанні для доступності: