Документація українською/ Publicism/ Як не слід писати статті

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

А. А. Шалито

Вступ

Пошук у Google за словами «як писати статті» видає 664 сторінки^google. Статті з такими назвами писали шановані люди — Г. А. Шенгелі, А. А. Шалито та інші. В цілому, однак, 664 сторінки — явний перебір. Річ ясна, більшість цієї писанини вигадана людьми, які писати статті не вміють. Якщо б вони вміли їх писати, то робили б це, а не навчали інших. Відверто кажучи, я не знаю, як слід писати статті. Проте за час моєї праці редактором я надивився на таку кількість потвор, якої вистачило б на декілька ленінградських Кунсткамер та ще залишилося б на декілька курортних виставок. Тому я достатньо добре уявляю собі, чого при цьому робити не слід. Про це я й спробую розповісти далі.

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

Шекспір

Як правило, робота над статтею починається зі складання плану. Звісно, можна покластись на натхнення і писати «як піде». Однак закінчити статтю за один день мало кому до снаги. А відновити наступного дня, не кажучи вже про тиждень, хід учорашніх міркувань вдасться далеко не завжди. Результат передбачуваний — оповідання, набравши розгону, звертає вбік. На цьому місці половина читачів, образно кажучи, вилітає в кювет. Розповідям про складні речі взагалі личить певна плавність і поважність — тут ліпше орієнтуватися на «Роллс-Ройс», ніж на «Феррарі».

Певна річ, ці слова, як правило, стосуються статей, спрямованих на поважне, всебічне висвітлення предмету. Однак дещо подібне трапляється і з невеличкими статтями, в яких ідеться про якийсь цікавий дріб'язок. Мова про авторські відступи від теми. Оскільки автор, як воно зазвичай буває, знає страх як багато, під час викладу йому несподівано спадає на думку аналогія, випадок із життя чи дуже важливе уточнення, яким просто не можна не поділитися з читачем. Однак у процесі цього відступу від теми йому несподівано спадає на думку (дивись вище). На третьому витку стаття остаточно сходить з орбіти і мчить кудись вже сама по собі, без керма, вітрил та гальмів. Звісно, потім автор спохоплюється й повертає до вихідної теми — але читач досі встиг забути, з чого, власне, все починалося.

Ми, ви та я

Цікаво спостерігати, як автор, почавши писати від третьої особи («Автор вважає»), на другій сторінці з'їжджає на «Ми будемо використовувати», а ще через декілька абзаців, остаточно впавши в відчай, каже: «візьміть ось це та викличте он те». В жодній з цих форм нема нічого поганого. Однак їх не слід використовувати як потрапить. Інакше можуть виникнути курйозні ситуації.

На відміну від англійської мови, українська терпиміша до безособових оповідних речень, які не містять особових займенників. Там, де в англійській статті обов'язково буде сказано: «You'd use it for smth.», українська прекрасно обійдеться чимось на кшталт «Це використовується так-то і так-то». Між іншим, численність особових займенників чітко вказує, в якому місці автор покинув викладати предмет своїми словами і вставив величезний клапоть з якогось джерела. Я не кажу, що це погано для суті статті, я просто хочу сказати, що це вносить стилістичну мішанину.

Пролог, епілог і дещо між ними

Вступ і висновок є майже у кожній статті. Сама стаття, яка за ідеєю повинна знаходитись між ними, є не завжди – але вступ і висновок пишуть практично всі. У попередніх реченнях важливі слова «майже» і «практично». Насправді це означає «далеко на завжди». Трапляються статті, що обриваються на півслові, хоч не так складно, наприклад, подякувати читачеві за те, що він дочитав ваш опус до кінця. Повірте, це часто достойно подяки.

Епічний зачин — вірна ознака недосвідченого автора. Якщо автор починає статтю про взаємоблокування, наприклад, з того, що довгі роки Microsoft, IBM та інші Оракли билися на цією проблемою, як буржуї з Червоною Армією, значить (з імовірністю в 90%), далі він розповість про те, як особисто він її вирішив — і це буде черговим винаходом екіпажу на двох колесах, який приводиться в дію мускульною силою. Заради справедливості слід сказати, що бувають і дійсно оригінальні міркування, і навіть багато – але їх автори, як правило, скромніше.

Хочеться сказати ще і про так званий «американський» стиль — коли висновок практично слово в слово повторяє вступ. Американці, до речі, так пишуть не часто, зате індуси і китайці просто обожнюють такі збочення. Не вірите — дивіться CodeProject. Нічого доброго у такому дублюванні нема – декілька повністю непотрібних абзаців, які розповідають читачеві, про що, власне, йшлося в щойно прочитаній ними статті. Якщо ви не знаєте, чим закінчити статтю, згадайте, навіщо взагалі потрібно було те, про що ви писали.

Телепатія на марші чи сага про праски

В чоловіка не випрасувані брюки. Але праски в нього нема. Він вирішує позичити праску у сусідки. Йде до сусідки і по дорозі міркує: «Зараз я прийду, попрошу праску. Сусідка — жінка культурна, запропонує зайти, випити чаю. Я відмовити не зможу, зайду. Туди-сюди, почнуться розмови, а жінка вона вродлива, та й я ніби нічого. Запропонує чогось міцнішого — я теж не зможу відмовитись. Так і до ліжка дійде. А я ж людина порядна, доведеться одружитись, і що далі? Пелюшки, сорочечки, лайки, розлучення...» З цією думкою він підходить до дверей сусідки й натискає кнопку дзвінка. Двері відчиняються, й чоловік випалює: «Та йди ти зі своєю праскою!»

старий анекдот

Цей анекдот відтворюється у кожній третій статті з тих, що поступають до редакції. Дивовижно, але факт — серед читачів рідко трапляються пророки і ясновидці. Вони й у житті нечасто трапляються. Що з цього виходить? Те, що усі міркування автору повинні бути викладені повністю. Читач, як правило, не в змозі відтворити хід думок автора, навіть якщо в нього є вихідна посилка і кінцевий результат. У тому місці, де хід міркувань пропущений, читач неминуче «спотикається» - тобто відволікається від суті статті, намагаючись зрозуміти, що мав на увазі автор. Знов включитися в оповідання йому складно, особливо якщо стаття присвячена якомусь складному питанню. Декілька таких помилок послідовно гарантовано вимусять читача кинути цю статтю.

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

Науковий і наукоподібний

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

Крім того науковий стиль повинен бути логічним, тобто послідовним, не суперечним і повним. Наукоподібність частіше всього скриває недоліки викладення, підмінюючи відсутність зрозумілих передумов і пояснень заплутаними і громіздкими формулюваннями. Сподівання, по всій видимості, на те, що читач, не розібравшись в написаному, подумає: «Яка розумна людина! Далеко мені до неї». Однак журнали і сайти читають багато висококваліфікованих спеціалістів, які не піддадуться на цей виверт. Мало того, серед них напевно знайдуться спеціалісти саме у цій області, які негайно виступлять з знищуючими коментарями. Це не просто зведе на нуль можливий ефект – це його перетворить в негативну величину.

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

У наукоподібного стилю є, тим не менш, незаперечна перевага. Якщо нормально написана стаття займає 10000 знаків, аналогічна їй наукоподібна займе не менш ніж 25000. При визначенні гонорару така різниця більш ніж істотна. Але тут встає питання – для чого ви пишете? Там де гонорарів не платять не вийде скористатися цією перевагою. А якщо вас переповнює альтруїзм і бажання наставити ближнього на шлях істинний – возлюбіть його хоч би малість, і не заставляйте продиратися скрізь наукоподібний бурелом.

Локація інстанціацій криптування у кустомізованих аплікаціях

Програмування – галузь, засмічена термінологічними ляпсусами, як жодна інша. Перелічувати ці ляпсуси можна дуже довго, але ви й самі легко згадаєте багато прикладів. Найбільш розповсюджене застосування кальок з англійської (від слова «калька», але можна і від «каліка» - суть не зміниться). Цей різновид потвор з'являється, коли автор у творчому запалі стахановськими темпами «ваяє нетленку», думаючи: «Потім виправлю». «Потім», як правило, настає після повернення матеріалу автору з редакторськими коментарями. Ще одне джерело – автору просто не вдається підібрати вдалий термін. І, нарешті, третій – спілкування у форумах і читання невдалих, ніким ніколи не редагованих статей в Інтернеті. Доводиться констатувати – Internet, невичерпне джерело відомостей про все на світі, є заодно і основним джерелом словесного сміття.

Кальки, які співпадають за звучанням з наявними словами, просто не припустимі – як, наприклад, наведена в заголовку «локація» у сенсі «місцезнаходження». «Локація» - це визначення місцезнаходження об'єкту, тобто процес. У слова «аплікація» теж є конкретне значення – це «спосіб створення орнаментів, зображень шляхом нашивання, наклеювання на тканинну, папір і таке інше різнокольорових клаптиків будь-якого матеріалу (тканинна, папір, хутро, солома і таке інше) іншого кольору чи вичинки, а також орнамент, зображення, створені у такий спосіб, який придає їм особливу рельєфність – Велика Радянська Енциклопедія».

Якщо ви збираєтесь використати термін, аналог якого підібрати складно, не пожалкуйте часу – звіртесь зі словниками і сайтами перекладачів (хоча б задайте питання на форумі «Переклади»), подивіться як цей термін перекладали до вас. Якщо словника під рукою нема, скористуйтесь сайтами www.lingvo.ru, www.translate.ru та www.gramota.ru^dicts. Якщо так нічого не знайшлося, можливо, ліпшим варіантом буде використання англомовного варіанту. Пам'ятайте, що такі слова не відмінюються, але якщо це приводе до поліпшення читабельності і зрозумілості, редакція закриє на це очі.

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

Особливим випадком є словосполучення. Наприклад, «key container» - це «сховище ключів» чи, як хочете, «контейнер ключів». Але ніяк не «ключовий контейнер». «Ключовий» - це «який має ключове, першорядне значення», а «ключовий контейнер» - це «головний, який має ключове значення, контейнер». Схожі помилки зустрічаються доволі часто, в основному з-за спроб дослівного перекладу англомовної фрази. Наприклад, «default value» регулярно намагаються перекласти як «умолчальне значення». В український мові нема слова «умолчальне», слід використовувати «типове значення»^default, але часто і цього буває недостатньо. Ось простий приклад:

SQL Server sets the referencing column values of the related rows in the referencing table to the default value of the column.

Невірний переклад:

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

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

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

SQL Server встановлює значення відповідних рядків колонки, що посилається у типове для цієї колонки значення.

Однак перекладом справа не обмежується. Є багато термінів, які люди бездумно використовують разом, не турбуючись по значення отриманого шедевру. Наприклад, сполучення двох термінів, які усвідомлюються окремо, може стати абсолютно безглуздим. Результат приголомшуючий – усі слова у реченні зрозумілі, але зрозуміти речення не вдається!

Редакційні коментарі і правка

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

Трапляється так, що автор ображається на зауваження редакції, чи вважає питання редакторів відверто глупими. Повторю: редактор – це перший читач вашої статті. Лише, це, за визначенням, причепливий читач. Він може чудово розуміти, що бажав сказати автор, але він також відмінно бачить, що необізнаний читач це місце статті не зрозуміє. А якщо і редактор не розуміє написаного, скоріш за все, це місце не зрозуміє більшість читачів. Нормальна реакція на коментарі – виправлення статті. Якщо ви не розумієте, що і як слід змінити, спробуйте «на пальцях» пояснити редактору у коментарі відповіді, що ви намагались сказати, і від спробує підібрати потрібні слова.

ПРИМІТКА:

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

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

Об'єм журнальної статті ...

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

Орфографія і пунктуація

Присвячується VladD2

Орфографія і пунктуація – це, певна річ, турбота редактора і коректора. Але у спеціалізованих виданнях з грамотністю, як ви можете бачити на багатьох прикладах, не так добре, як в загально-політичних і навіть науково-популярних. Проблема у тому, що коректор багато термінів бачить у перший раз, а не розуміє практично всі. Тому він їх або не виправляє, сподіваючись на редактора, або – що ще гірше – виправляє за своїм розумінням. Редактор, у свою чергу, все розуміє, але сподівається на коректора. Особливо схильні цій напасті коментарі у коді і ілюстрації – тому що їм випадає менше всього уваги. Всі вважають, що це їх не стосується. Науковий редактор вважає, що все, що українською – це до літературного, літературний – що код в провадженні наукового, а ілюстрації – це взагалі художнику, коректор же обачно взагалі не торкається ані коду, ані малюнків – від гріха подалі. Результат може бути дуже невтішним. Тому не вважайте, що редакція виправить усі ачіпяткі і проставте усі коми. Згадайте, що все ж таки ви пишете рідною мовою, і віднесіться до неї, як до рідної. До речі, «ви» пишеться з великої літери лише при особистому зверненні.

Коректність виводів

Статті, пов'язані з програмуванням – це суто технічні статі, якщо вони, звичайно, не відносяться до розділу «Колеги, посміхніться». Питання віри в таких статтях недоречні. Якщо ви робите якесь твердження, воно повинно бути належним чином обґрунтовано – тестами, замірами чи логічними виводами.

Тести

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

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

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

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

Масштаб

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

Велосипед

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

А. і Б. Стругацькі, «Понеділок починається в суботу»

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

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

Не бійтеся, що вашу ідею вкрадуть. Якщо ви все ж таки побоюєтесь злих конкурентів, запатентуйте ідею. Але у цьому випадку вам все одно буде необхідно довести її новизну. :)

Висновок

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

цієї статті. Англійською «How to write an article» видасть близько 127 мільйонів результатів.

(нажаль, перехоплений (інакше не скажеш) lingvo), http://e2u.org.ua, http://r2u.org.ua, http://dict.linux.org.ua, http://linux.org.ua та матеріали на цьому вікі.

відповідно, хоча він тепер більше не релевантний — українська мова гнучкіша.