Разработка программного обеспечения - это не только общение, но и функциональность. По своей сути код отражает бизнес-процессы и бизнес-логику. Программное обеспечение никогда не существует исключительно в вакууме, оно окружено как контекстом, так и людьми. Отслеживание истории бизнеса и его программного обеспечения становится все более важным фактором всего процесса разработки. В идеальном мире мы документируем изменения, мы пишем заметки, мы добавляем комментарии, и эта документация представляет целостный взгляд на наше программное обеспечение и процессы не только в настоящее время, но и на протяжении его срока службы. Реальность такова, что часто этот целостный взгляд намного уже, документация неполна или неуместна; то есть если документация вообще существует.
Документация сэкономила время и деньги, спасла сломанное программное обеспечение, повысила эффективность, ускорила доставку и помогла исправить пару ошибок. Отношения многих инженеров с термином Документация часто в лучшем случае чреваты; но этого не должно быть. Документация - это не просто сноска внизу страницы или комментарий над строкой кода; это то, как мы делимся информацией, как мы помогаем тем, кто после нас, понять причину решения, будь то коллега или ваше будущее.
Документация - это больше, чем просто слова.
В идеале, когда программное обеспечение ломается, есть другое программное обеспечение, которое исправит это. Более вероятен сценарий, когда мы находим в Интернете Руководство по устранению неполадок с подробным набором ручных шагов, которые помогут сделать это самостоятельно. Обученный искусственный интеллект будет работать быстрее и в конечном итоге лучше. Написание руководства по устранению неполадок всегда будет намного дешевле, чем создание интеллектуальной машины для решения наших проблем. Как инженеры, мы часто упускаем из виду эти простые решения или считаем их неэффективными. Документация требует небольших затрат и относительно небольших усилий, а также эффективно и действенно решает проблемы в правильных обстоятельствах. Если проблему можно решить, выполнив десятки ручных действий, значит, это решенная проблема, какой бы неэффективной она ни была. Даже такое решение может быть записано, задокументировано и прочитано другими. Задача не стала проще, но ее решение больше не ограничивается доступностью отдельного человека или команды, их приоритетами, графиком работы или темпераментом. Документ никогда не утомляет, не требует перерывов в ванной и никогда не забывает никаких деталей. Пока существует документ, будет существовать и содержащаяся в нем информация. Возможно, это не автономный искусственный интеллект, но, тем не менее, это решение.
Что такое документация?
Документация существует во многих формах. Прежде всего, это косвенная и асинхронная среда для передачи информации. Это устраняет необходимость в прямом и синхронном общении между людьми. Для этого нужен общий язык между общающимися участниками. Язык - мощный инструмент, который мы используем каждый день. Мы разговариваем с нашим коллегой поблизости, чтобы исправить неработающую ссылку на электронную почту, мы звоним нашему соседу, чтобы узнать, собирают ли мусор во вторник или среду. Мы ищем ответы на наши вопросы в максимально доступном режиме общения. В то время как разговорный язык является наиболее распространенным методом общения, письменные и визуальные формы позволяют нам передать процесс общения посреднику. Как разработчик программного обеспечения, документация существует в виде комментариев к коду, статей вики, файлов README и самого кода. Определяя документацию как любой асинхронный носитель для передачи информации, мы начинаем охватывать больше форм документации, включая электронные письма и даже твиты. Код, который мы пишем, документирует процесс, который в конечном итоге запускается на компьютере, а вспомогательная документация служит для дальнейшего документирования того, как был написан код и почему он был написан. Документы начинают документировать другие документы, и возникает иерархия документации.
Юрист с большей вероятностью столкнется с описаниями дел, повестками в суд, контрактами и судебными разбирательствами, каждый документ сам по себе является как артефактом, так и подтверждающей документацией для другого. И юридически обязательный контракт, и README представляют собой часть информации, которая помогает нам лучше понять данную ситуацию. Каждый документ в иерархии предоставляет контекстную информацию и вместе формирует более четкое понимание окружающей проблемы, чем любой отдельный документ. Комментарий к коду объясняет особенно запутанную строку кода, в контракте излагается юридическое соглашение, а набор требований проливает свет на основные мотивы, лежащие в основе решения проблемы клиента. Каждый документ представляет собой фрагмент информации. Документация однозначно является средством передачи этой информации друг другу.
README не поможет мне понять непонятную строку кода, равно как и контракт. Юридические обязательства, вытекающие из подписанного контракта, повлияют на проект, связанный с конфиденциальностью данных, и, кроме того, это повлияет на мои юридические обязательства как разработчика программного обеспечения и код, реализующий эти требования. Комментарий к коду и контракт вместе объединяют более полное представление о проблеме, несмотря на то, что каждый из них направлен на решение разных частей проблемы. Дополнительный фон и контекст помогают принимать более правильные решения, даже если решение заключается в изменении одной строчки кода.
Проблема контекста
Чем больше информации, контекста и предыстории будет у человека до принятия решения, тем лучше мы примем решение. В мире программной инженерии принято считать, что код должен читаться как любой другой хорошо структурированный и организованный документ. Как вы называете переменную, так же важно, как и то, как она используется. Чем легче кому-то, читающему ваш код, понять не только то, что он делает, но и почему он это делает, тем меньше времени ваш читатель будет тратить на сканирование Интернета для устранения проблемных моментов. Комментарии к коду и README облегчают понимание кода, но часто предоставляют очень мало информации и контекста о том, какую проблему решает код и как код со временем эволюционировал.
Американский философ Джордж Сантаяна однажды сказал: «Те, кто не помнит своего прошлого, обречены на повторение своих ошибок». История программного продукта, бизнес-процесса или отдельной строки кода может предоставить контекст того, почему он существует в текущем состоянии. У вашего бизнеса может быть концепция учетной записи, эта сущность существует, ее можно создавать, изменять, удалять, и ее информация может передаваться в рамках всей компании, а также клиентам, но зачем она нужна ? Какую проблему решает аккаунт? Как это решает эту проблему? Если эта информация не записана, она часто навсегда теряется для истории. Это может быть правдой, что каждая учетная запись должна иметь уникальное имя, это правило может быть рассуждено, причина его существования может быть обсуждена, но если проблема, которую решает это правило, не задокументирована, если это правило когда-либо будет изменено, проблема, которую оно решает, будет появляются снова. Документация не только решает проблему того, что существует, но и почему существует и как развивалось.
Неизбежные предположения
Любая часть документации делает некоторые предположения о ее читателе. Первое и самое главное предположение состоит в том, что вы знакомы с языком (ами), на котором он написан. Дальнейшие предположения делаются относительно биографии читателя, его роли, общих знаний и даже стиля мышления.
Написание исчерпывающей документации - нелегкая задача. Когда мы пишем для аудитории, мы адаптируем наш язык и наши предположения к этой аудитории. Чем конкретнее аудитория, тем труднее будет понять читателей за пределами этой аудитории. Контекст важен. Бизнес-отчеты вряд ли будут прочитаны той же аудиторией, что и ваши комментарии к коду.
Документация, написанная с очень небольшим количеством предположений о читателе, может быстро превратиться в роман, начинающийся со слов «Давным-давно, в стране далеко-далеко…». Когда предполагаемого контекста слишком мало, документация может превратиться в сложную сеть из дуг персонажей, сюжетных линий и метафор. Глубоко в этом документе, вместе с набором в основном не относящейся к делу информации, вы можете найти то, что вам нужно. Вы открывали этот документ не для того, чтобы читать захватывающий роман, вам нужна была информация. У вас уже есть четкое представление о продуктах, процессах и общих проблемах вашей компании. Предположения сокращают усилия по созданию документации и делают ее более краткой для аудитории, уже находящейся в этом контексте.
С другой стороны, когда о читателе делается слишком много предположений, пробелы в их понимании позже проявятся в проблемах. Чем больше предположений сделано о читателе, тем больше вероятность, что предположение окажется неверным. Автор Устранение неполадок Руководства может опустить ключевые шаги, которые он считает очевидными или подразумеваемыми. Предположение, которое неверно в 10% случаев, становится неверным в 10% случаев. Хотя это может быть приемлемо в контексте неисправного маршрутизатора, при документировании критически важных задач частота ошибок в 10% представляет собой потенциально катастрофический риск, на который многие не захотят пойти. Чем меньше предположений о нашей аудитории сделано, тем меньше вероятность того, что будет сделано неверное предположение.
Улучшение того, как мы делаем документацию
Всегда есть возможности для улучшения того, как мы передаем важную информацию от одного человека к другому. Документация наиболее эффективна, когда она доступна тем, кто в ней нуждается. Наиболее важными аспектами, которые можно улучшить, являются контекст, обнаруживаемость и ясность.
Контекст
Контекст, необходимый читателю, зависит от самой проблемы. В то время как меньшее количество предположений о читателе приводит к меньшему количеству неверных предположений, их слишком мало и ключевая информация может быть потеряна. Должно быть столько контекста, сколько необходимо, и не более того. Пишите для ожидаемой аудитории. Хотя вы можете свести к минимуму свои предположения о своей аудитории и ее необходимых знаниях, полностью избежать их практически невозможно. Четко изложите предположения, которые вы сделали относительно своей аудитории. Четко излагая свои предположения, читатель может определить пробелы в своих собственных знаниях.
Обнаруживаемость
Возможность поиска документации так же важна, как и сама документация. Чем ближе информация к тому месту, где она нужна, тем больше вероятность, что она решит проблему, если и когда она возникнет. При написании документации не забывайте, где этот документ должен находиться, чтобы помочь вашей аудитории найти решение, которое им нужно, в то время, когда оно им больше всего нужно. Документация, которая кажется не имеющей отношения к проблеме, чаще всего просто неуместна. Документация, которая ясна и кратка, но не имеет отношения к рассматриваемой проблеме, по-прежнему ценна, она просто нужна где-то еще.
Храните документацию там, где она понадобится.
Ясность
Независимо от того, насколько легко вы можете найти документ, непонятный или структурный беспорядок, понимание содержащейся в нем информации становится все труднее. Единственная цель документации - передать информацию. Текст и изображения представляют собой фантастические способы общения, которые позволяют выражать сложные идеи. Однако они очень подвержены шуму и неверному толкованию. Передача информации с помощью языка и изображений - это занятие, требующее осторожности и точности. Будьте осторожны со своими словами и подумайте, как каждое из них будет понято вашей аудиторией. Поскольку слова составлены в предложения, а предложения - в абзацы, структура самого документа так же важна, как и слова в нем. Документ существует, чтобы помочь другим найти информацию. Простота как в нашем языке, так и в нашей структуре снижает усилия других, чтобы понять ее. Мы должны структурировать нашу документацию так же, как мы структурируем наш код: каждый раздел должен быть кратким и лаконичным, группировать схожую информацию и разделять различные группы информации на связанные разделы.
Сделайте это простым.
Держите его структурированным.
Будьте ясны.
Будьте краткими.
У нас плохие отношения с термином документация, но так быть не должно.
Документация - дешевое и эффективное решение многих проблем.
В следующий раз вы лицом к лицу сталкиваетесь со сложной проблемой, начните с простого решения.
Запишите ее.
