Нашёл у себя в ящике стола один очень старый каталог книг Microsoft Press за 1988–89 годы. Мне нравится иногда его доставать, перечитывать описания компьютерных книг тех лет, разглядывать их обложки. Да и просто названия книжек из этого проспекта заставляют погрузиться в ностальгическое настроение.

Сейчас заметную часть моей библиотеки по-прежнему составляют книги по программированию. Но я всё чаще задумываюсь о том, стоит ли покупать бумажные издания по компьютерной тематике...

У химиков есть известная байка, которую они любят рассказывать молодому поколению. Главный герой этой истории — студент, который пошагово воспроизводил методику одного химического эксперимента из учебника. Он старательно выполнил очередной шаг «добавьте азотную кислоту» и... в лаборатории прогремел взрыв! Когда впоследствии стали разбираться, в чём же дело, выяснилось, что на следующей странице учебника было написано: «... медленно, по каплям».

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

Как же лучше писать и оформлять примечания в технических текстах?

Мир находится в постоянном движении, вид за окном неуловимо меняется каждую секунду и никогда не повторяется дважды. Однако мы привыкли к относительной стабильности окружающей реальности. Будущее пугает нас своей неизвестностью и непредсказуемостью. Мы пытаемся его прогнозировать, строить какие-то долгосрочные планы. Но в любой момент может произойти «маловероятный» катаклизм и мы поймём, что все прогнозы погоды оказались пустышкой. Совсем другое дело — прошлое. Оно кажется нам надёжным и неизменным...

«Ваша документация — отстой!», «Я её никогда не читаю, всё равно там ерунда написана!», «Эти документаторы опять всё напутали», «Да любая нейросеть быстро напишет это в сто раз лучше», «Там никогда не найти ничего нужного», «А разве у нас есть документация?»

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

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

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

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

Давайте ненадолго перенесёмся в школьные годы и вспомним уроки математики и физики. Помните, чему равно число π? Естественно, помните, мы же на Хабре! А чему равно π в квадрате? Это тоже странный вопрос. Конечно, 9,87. А чему равно ускорение свободного падения g помните? Ещё бы, это число так тщательно вдолбили в нашу память, что захочешь — не забудешь: 9,81 м/c². Конечно, оно может варьироваться, но для решения базовых школьных задачек мы обычно использовали именно это значение.

А теперь, внимание, следующий вопрос: а с какого это перепугу π² примерно равно g?

В статье я хочу рассказать об одной очень интересной теории разработки документации на системы и программы. Её авторы утверждают, что создали ни много ни мало «Великую Единую Теорию Документации» (The Grand Unified Theory of Documentation). Мы привыкли с опаской относиться к заявлениям о том, что кто-то обнаружил сокровенную истину и раскрыл её профессиональному сообществу. В теории изложены идеи и правила, которые мы встречаем в разных методиках разработки документации и сами применяем на практике.

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

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

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

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

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

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

Какую программу вы обычно запускаете сразу после загрузки операционной системы? Кто-то сразу стартует браузер — поглядеть, кто там сегодня в Интернете (на Хабре) неправ. У многих — это редактор кода: «Я, как утром встал, сразу за дрель!». Возможно, вы сначала привычно открываете мессенджеры и почту — проверить, что там нового и важного.

Я обычно сразу после запуска операционки открываю свой Любимый Файловый Менеджер. Это «переходящее звание» — в разные периоды моего компьютерного прошлого этой чести «удостаивались» разные приложения с классическим двухпанельным интерфейсом. Сначала это был простой, но универсальный Norton Commander. Потом появился DOS Navigator со всяческими классными фичами: CD-плеер, телефонная книга с дозвоном по модему, встроенный табличный редактор и прочие прекрасные и поразительные для тех лет вещи.

Когда Windows прочно вытеснил DOS и все понемногу забыли про файл autoexec.bat, звание моего любимого файлового менеджера плавно перешло к Total Commander. Он продержался довольно долго, но в какой-то момент в мою жизнь буквально ворвался FAR...

Барометр не только помогает следить за погодой, но и вдохновляет на создание простых, надёжных и практичных, но в чём-то особенных и необычных вещей. Для меня барометр — реальное воплощение закона Артура Кларка, по которому любая достаточно продвинутая технология неотличима от магии...

В одном из выпусков библиотеки журнала «Квант» я обнаружил перевод книги Льюиса Кэрролла «Логическая игра» (The Game of Logic). В ней автор рассказывает об оригинальном графическом способе визуализации логических суждений с помощью размеченного особым образом квадратного поля и фишек двух цветов. Этот способ помогает легко оперировать логическими множествами и на основе некоторых предпосылок формулировать новые утверждения. Давайте попробуем разобраться, как это работает.

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

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

Книга — предмет настолько универсальный и всеобъемлющий, что у каждого найдётся свой уникальный и самобытный способ с ней взаимодействовать. Такие способы, правила и методы есть и у меня. С годами они накапливались и менялись, в результате все они сложились в своеобразную систему, которая помогает мне ещё глубже погрузиться в мир книги, сделать процесс чтения ещё ярче и интереснее, ещё лучше понимать мысли и идеи автора, ещё искуснее читать между строк. Хочу поделиться с вами несколькими правилами из моей системы.

Одним из моих любимых развлечений в детстве была родительская печатная машинка. Когда она была свободна, я часами сидел и печатал: книги, брошюры, газеты. Каждое издание выходило тиражом в три экземпляра — под копирку. Иллюстрации и переплёт были выполнены вручную. У меня до сих пор сохранились некоторые забавные образцы моей тогдашней издательской деятельности...

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

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

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

Конечно, в любой книге главное — это автор. Именно он её придумал и написал, именно ради его идей мы покупаем и читаем книгу. Но автор сочинял её на другом языке, а это — не только другие, незнакомые слова, но ещё и другой образ мысли, другой контекст, другая культура.

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

Как их только не называют: техписы, техрайтеры, документаторы... Хорошо, хоть не архивариусы!

Спрос на хорошую, качественную документацию к программам и системам постоянно растёт. При этом сейчас на рынке наблюдается серьёзный дефицит профессиональных технических писателей. Опытные технические писатели сейчас буквально на вес золота. Во всём мире профессия technical writer (или technical author) считается престижной и перспективной. Техническое документирование — это одна из замечательных пограничных областей для тех, кто так и не смог смириться в школе с разделением на гуманитариев и математиков.

Вы работаете программистом и практически каждый день пишете код. Скажите, как часто вы чувствуете удовлетворение от выполненной работы и гордость за результаты своего труда? Случалось ли вам выпускать работающий, но некачественный и «некрасивый» код только для того, чтобы уложиться в сроки? Есть ли у вас мотивация писать оптимальный код, зная, что через пару месяцев он станет неактуальным и бесполезным?

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

— Это ты тестировал систему продажи билетов?
— Да…
— Клиент сейчас купил билет на дату «82.13.-891». Либо ты сейчас скажешь ему, сколько дней осталось до поездки, либо переводим тебя на должность стажёра.

Нравится ли вам наш календарь? Если вы программист, то, наверное, не очень. Несмотря на то, что во всех современных языках программирования есть удобные инструменты для выполнения действий с временем и датами, работа с календарём остаётся не самой простой задачей, всё время приходится идти на какой-то компромисс.