Сообщений 17    Оценка 3267 [+8/-1]         Оценить  
Система Orphus

Как не надо писать статьи

Автор: Михаил Купаев (Kupaev)
The RSDN Group

Источник: RSDN Magazine #6-2004
Опубликовано: 14.03.2005
Исправлено: 29.11.2006
Версия текста: 1.0
Введение
Мы, вы и я
Пролог, эпилог и нечто между ними
Телепатия на марше, или сага об утюгах
Научный и наукообразный
Локация инстанциаций криптования в кустомизированных аппликациях
Редакционные комментарии и правка
Объем журнальной статьи...
Орфография и пунктуация
Корректность выводов
Тесты
Масштаб
Велосипед
Заключение

Если время, потраченное на написание и чтение статьи, константа,
то львиная доля его должна быть потрачена Писателем.
А.А.Шалыто

Введение

Поиск в Google по словам "как писать статьи" выдает 664 страницы. Статьи с таким названием писали столь уважаемые люди, как Г.А. Шенгели, А.А.Шалыто и др. Но в целом, 664 страницы - это, конечно, перебор. Понятно, что большая часть этого моря писанины сочинена людьми, писать статьи не умеющими. Если бы они умели писать статьи, они их писали бы, а не учили других. Признаюсь честно – я не знаю, как надо писать статьи. Зато за время своего редакторства я насмотрелся на такое количество уродцев, которого хватило бы на пару питерских Кунсткамер, и еще осталось бы на несколько курортных выставок. Поэтому я достаточно хорошо представляю себе, чего при этом делать не нужно. Вот об этом-то я и попытаюсь рассказать ниже.

Так начинанья, взнесшиеся мощно,
сворачивая в сторону свой ход,
теряют имя действия...
Шекспир.

Как правило, работа над статьей начинается с составления плана. Можно, конечно, положиться на вдохновение и писать "как пойдет". Однако закончить статью за один день мало у кого получается. А восстановить на следующий день (тем более – через неделю) последовательность вчерашних рассуждений удается далеко не всегда. Результат предсказуем – повествование, набрав разгон, сворачивает в сторону. На этом месте половина читателей, образно выражаясь, улетает в кювет. Рассказу о сложных вещах вообще приличествует некоторая плавность и степенность – здесь лучше ориентироваться на "Роллс-Ройс", а не на "Феррари".

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

Мы, вы и я

Интересно наблюдать, как автор, начавший писать от третьего лица ("Автор считает"), ко второй странице съезжает на "Мы будем использовать", а через еще пару абзацев, окончательно отчаявшись, говорит: "возьмите вот это и вызовите вон то". Ни в одной из этих форм нет ничего плохого. Однако их не стоит использовать как попало. Иначе могут возникнуть курьезные ситуации.

Кстати, русский язык, в отличие от английского, куда более терпим к безличным повествовательным предложениям, не содержащим личных местоимений. Там, где в английской статье непременно будет сказано: "You'd use it for smth.", русский прекрасно обойдется чем-то вроде "Это используется так-то и так-то". Между прочим, обилие личных местоимений четко указывает, в каком месте автор бросил излагать предмет своими словами и вставил здоровенный кусок из MSDN. :) Я не говорю, что это плохо для сути статьи, я просто хочу сказать, что это вносит стилистический разнобой.

Пролог, эпилог и нечто между ними

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

Эпический зачин – верный признак неопытного автора. Если автор начинает статью о взаимоблокировках, например, с того, что долгие годы Microsoft, IBM и остальные Ораклы бились над данной проблемой, как буржуины с Красной Армией, значит (с вероятностью в 90%), дальше он расскажет нам о том, как он лично ее решил – и это будет очередным изобретением двухколесного экипажа, приводимого в действие мускульной силой. Справедливости ради надо сказать, что бывают и действительно оригинальные рассуждения, и даже много – но их авторы, как правило, скромнее.

Хочется сказать еще и о так называемом "американском" стиле – когда заключение практически дословно повторяет вступление. Американцы, кстати, так пишут нечасто, зато индусы и китайцы просто обожают такие извращения. Не верите – см. CodeProject. Ничего хорошего в таком дублировании нет – несколько совершенно ненужных абзацев, рассказывающих читателю, о чем, собственно, была только что прочитанная им статья. Если уж вы не знаете, чем закончить статью, вспомните, а ради чего нужно то, о чем вы писали?

Телепатия на марше, или сага об утюгах

У мужика не поглажены брюки. Но утюга у него нет. 
Он решает одолжить утюг у соседки.
Идет к соседке и по дороге размышляет:
"Сейчас я приду, попрошу утюг.
Соседка – женщина культурная, предложит зайти, выпить чаю.
Я отказаться не смогу, зайду.
То-се, начнутся разговоры, а женщина она красивая, да и я вроде ничего.
Предложит чего покрепче – я тоже не смогу отказаться.
Так и до койки дойдет. А я – человек честный, придется женится, и что дальше?
Пеленки, распашонки, ругань, развод..."
С этой мыслью он подходит к двери соседки и нажимает на кнопку звонка.
Дверь открывается, и мужик выпаливает:
"Да пошла ты со своим утюгом!" (с)старый анекдот

Этот анекдот воспроизводится в каждой третьей статье из поступающих в редакцию. Удивительно, но факт – среди читателей редко попадаются пророки и ясновидцы. Они и в жизни-то нечасто встречаются. Что из этого следует? То, что все рассуждения автора должны быть изложены полностью. Читатель, как правило, не в состоянии воспроизвести ход мыслей автора, даже если у него есть исходная посылка и конечный результат. В том месте, где ход рассуждений пропущен, читатель неизбежно "спотыкается" – то есть отвлекается от сути статьи, пытаясь понять, что имел в виду автор. Снова включиться в повествование ему непросто, особенно если статья посвящена какому-нибудь сложному вопросу. Несколько таких оплошностей кряду гарантированно заставят читателя бросить эту статью.

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

Научный и наукообразный

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

Кроме того, научный стиль обязан быть логичным, то есть последовательным, непротиворечивым и полным. Наукообразие же чаще всего скрывает недостатки изложения, подменяя отсутствие внятных предпосылок и объяснений запутанными и громоздкими формулировками. Расчет, по всей видимости, на то, что читатель, не разобравшись в написанном, подумает: "Умный какой человек! Далеко мне до него". Однако наш журнал (и сайт) читает немало высококвалифицированных специалистов, которые не поддадутся на эту уловку. Мало того, среди них наверняка найдутся специалисты именно в этой области, которые не замедлят выступить с уничтожающими комментариями. Это не просто сведет на нет возможный эффект – это его обратит в отрицательную величину.

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

У наукообразного стиля есть, тем не менее, неоспоримое достоинство. Если нормально написанная статья занимает 10000 знаков, аналогичная ей наукообразная займет не менее 25000. При определении гонорара такое различие более чем существенно. Но тут встает вопрос – для чего вы пишете? В RSDN Magazine не платят гонораров, так что воспользоваться данным преимуществом не выйдет. А если вы и впрямь полны альтруизма и желания наставить ближнего на путь истинный – возлюбите его хотя бы малость, и не заставляйте продираться сквозь наукообразный бурелом.

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

Программирование – отрасль, замусоренная терминологическими ляпсусами, как никакая другая. Перечислять эти ляпсусы можно очень долго, впрочем, вы и сами легко вспомните множество примеров. Наиболее распространено применение калек с английского (от слова "калька", но можно и от слова "калека" – суть не изменится). Этот подвид уродцев появляется, когда автор в творческом порыве стахановскими темпами ваяет нетленку, думая:"Потом поправлю". "Потом", как правило, наступает после возвращения материала автору с редакторскими комментариями. Еще один источник – автору просто не удается подобрать удачный термин. И, наконец, третий – общение в форумах и чтение неудачных, никем никогда не редактированных статей в Сети. Приходится констатировать – Internet, неисчерпаемый источник сведений обо всем на свете, является заодно и основным источником словесного мусора.

Кальки, которые совпадают по звучанию с имеющимися словами, просто недопустимы – как, например, приведенная в заголовке "локация" в смысле "местоположение". "Локация" в русском языке – это определение местоположения объекта, то есть процесс. У слова "аппликация" тоже есть конкретное значение в русском языке – это "способ создания орнаментов, изображений путём нашивания, наклеивания на ткань, бумагу и т. п. разноцветных кусочков какого-либо материала (ткань, бумага, мех, соломка и т. п.) другого цвета или выделки, а также орнамент, изображение, созданные по такому способу, придающему им особую рельефность – БСЭ".

Если вы собираетесь употребить термин, русский аналог которого подобрать затруднительно, не пожалейте времени – справьтесь со словарями и переводческими сайтами (хотя бы задайте вопрос на нашем форуме "Проблемы перевода"), посмотрите, как этот термин переводили до вас. Если словаря под рукой нет, воспользуйтесь сайтами www.lingvo.ru, www.translate.ru и www.gramota.ru. Если так ничего и не нашлось, возможно, лучшим вариантом будет использовать англоязычный вариант. Помните, что такие слова не склоняются, но если это приводит к улучшению читаемости и понятности, редакция закроет на это глаза.

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

Особый случай представляют словосочетания. Например, "key container" – это "хранилище ключей" или, если угодно, "контейнер ключей". Но никак не "ключевой контейнер". "Ключевой" – это "имеющий ключевое, первостепенное значение", а "ключевой контейнер" — это "главный, имеющий ключевое значение, контейнер". Подобные ошибки встречаются довольно часто, в основном из-за попыток дословного перевода англоязычной фразы. Например, "default value" регулярно пытаются перевести как "умолчальное значение". В русском языке нет слова "умолчальное", правильнее, конечно, использовать "значение по умолчанию", но и этого зачастую бывает недостаточно. Вот простой пример:

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

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

Корректность выводов

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

Тесты

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

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

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

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

Масштаб

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

Велосипед

"Я нашел, как применить здесь нестирающиеся шины из 
полиструктурного волокна с вырожденными аминными связями 
и неполными кислородными группами. 
Но я не знаю пока, как использовать регенерирующий 
реактор на субтепловых нейтронах. Миша, Мишок! Как быть с реактором?" 
Присмотревшись к устройству, я без труда узнал велосипед.
А. и Б. Стругацкие, Понедельник начинается в субботу.

Это славное устройство для перемещения в пространстве уже упоминалось выше, но повториться все же стоит. Если вам пришла в голову гениальная идея, до которой пока не додумался никто другой, не торопитесь создавать трактат на эту тему. Проверьте – возможно, эта идея пришла в голову не только вам. Например, изложите ее коротко в соответствующем по тематике форуме – например, в "Философии программирования" на RSDN. Если идея не нова, вы узнаете об этом буквально за день-другой – у нас полно желающих крикнуть "Баян" по любому поводу.

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

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

Заключение

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


Эта статья опубликована в журнале RSDN Magazine #6-2004. Информацию о журнале можно найти здесь
    Сообщений 17    Оценка 3267 [+8/-1]         Оценить