28 июля 2021 г.

Умение понятно писать – один из самых недооцененных инженерных навыков

Мне кажется, что умение понятно писать – ясно излагать мысли, создавать понятные описания и ясные инструкции, формулировать четкие вопросы и давать полезные ответы – один из самых недоразвитых сейчас навыков среди инженеров. Недоразвитых, и недооцененных.

Я сейчас не говорю о техническом писательстве как профессиональном навыке. Я говорю о более поверхностном – но и более универсальном – умении излагать свои мысли письменно, связно и понятно для читателя.

Конечно, есть миллион других навыков, которые не помешали бы инженеру, но я выделяю этот, потому что это low hanging fruit: большинство инженеров уже умеют думать, и уже хорошо разбираются в предмете. Не хватает, по-моему, малого – немного научиться думать о читателе.

Я говорю о совсем простых вещах, вроде

  • задуматься, как побыстрее сориентировать читателя – стоит ли ему вообще читать
  • задуматься, как побыстрее и поточнее погрузить читателя в контекст
  • задуматься, что читателю интересно и важно в первую очередь, что – во вторую, а что, скорее всего, вообще не интересно, и только запутает

Это удивительно универсальные простые вещи: они подсказывают, как писать понятные людям email-ы и сообщения в мессенджерах, как писать полезные комментарии в коде, как составлять читабельные инструкции и отчеты, и даже как строить презентации. Может, и в других случаях тоже помогают, но я пока не пробовал.

И чтобы их освоить на базовом уровне – достаточно прочитать 3-4 главы "Пирамиды Минто"1. Это пара вечеров на прочтение, и пара недель на попрактиковаться без отрыва от производства – но почему-то даже такой базовый уровень встречается у одного из 4-5 инженеров.

И это очень обидно, ведь неумение понятно писать часто обесценивает хорошую техническую, инженерную работу!

В последние полтора года недостаток этого умения писать думая о читателе очень бросается в глаза: объем переписки сильно возрос, большое количество усного общения перешло в письменную форму, и это адищще – переписка и так гораздо медленнее усного общения, но она затягивается еще в полтора-два раза, так как участники не могут сразу ясно сформулировать свою мысль.

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

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

В обоих этих – и многих других, похожих – случаях встает вопрос: что мешало автору описать свою систему – из каких идей и ограничений сложился дизайн, и как этим всем пользоваться?

Когда я задаю этот вопрос, обычно слышу в ответ что-то про недостаток времени. Но я думаю, что это миф: настоящая причина в недостатке навыка, а не времени.

Потому что для проекта в сотни тысяч строк кода – достаточно всего пары десятков страниц, чтобы описать ключевые идеи и концепции, и проинструктировать по основным приемам использования. То есть объем минимально-полезной документации (minimal valuable documentation, MVD) – единицы процентов от объема кода, а польза от нее огромна – несоизмерима с процентами дополнительных затрат.

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

Примечания

  1. Barbara Minto "The Pyramid Principle: Logic in Writing and Thinking"/"Принцип пирамиды Минто®. Золотые правила мышления, делового письма и устных выступлений"

    Книга Барбары Минто – классика организации деловой переписки, и вообще аргументированного письма. По мне, так это полноценный учебник письменной риторики. Издается, кажется, еще с 1970-х, и совершенно не устарела. Книга довольно большая, очень детальная, и немного занудная, но самые важные принципы изложены уже в первых 3-4 главах – для первого знакомства нет необходимости читать все.↩︎

4 комментария:

  1. Добавлю к твоему ворчанию своего: позывы к написанию документации часто заглушаются пониманием, что никто, абсолютно никто не будет ее читать. Реально, людей, которые могут сесть и реально вдумчиво прочитать несколько десятков страниц документации еще меньше, чем людей, которые могут ее написать. Поэтому я пишу скорее только когда чувствую, что текст пригодится в будущем _мне самому_.

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

    Если не видел, вот интересный тред на эту тему: https://twitter.com/levwalkin/status/1327440814604124160

    Спасибо за рекомендацию книжки. На похожую тему, есть https://en.wikipedia.org/wiki/How_to_Read_a_Book (1972), одна из лучших книг которую я читал.

    ОтветитьУдалить
    Ответы
    1. >Реально, людей, которые могут сесть и реально вдумчиво прочитать несколько десятков страниц документации еще меньше, чем людей, которые могут ее написать.

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

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

      >Если не видел, вот интересный тред на эту тему: https://twitter.com/levwalkin/status/1327440814604124160

      Нет, не видел, спасибо -- очень клевый тред, очень со многим согласен (планирую написать пост про свой небольшой опыт, если будет время)

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

    ОтветитьУдалить
    Ответы
    1. >силы тратить на нее не хочется.

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

      Поэтому, хотя я согласен со всеми аргументами насчет актуальности -- но я смотрю на это как открытый вопрос: _какую_ документацию стоит писать (=оправдывается с точки зрения соотношения затрат/отдачи), а какую нет. В _какой_ форме писать документацию в этом конкретном случае: в комментариях, в виде тестов-примеров, в человеческом виде на вики?

      Например: если то документация какой-то фичи быстро теряет актуальность -- значит и сама фича быстро теряет актуальность (удаляется или сменяется другой фичей). Может это не очень важная фича, зачем ее документировать?

      Если все-таки нужно, то, может быть, в комментариях -- там проще поддерживать актуальность?
      Или в виде тестов -- менее читабельно, зато актуальность проверяется автоматически?

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

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

      Удалить