Важность хорошей документации

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

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

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

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

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

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

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

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

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

В любом случае, если вы обнаружили недокументированные функции, вам необходимо провести собственное исследование. Если это программное обеспечение, написанное той же командой, вы можете просто спросить того, кто его написал (спасибо git blame!) и получить ответы. Но если программа написана сторонним разработчиком, вы можете либо никогда не узнать ответ, либо вам придется поднять тикет и надеяться на правильный и своевременный ответ.

Именно поэтому документация должна быть актуальной или вообще отсутствовать. Если бы документации вообще не было, а программное обеспечение было бы самодокументирующимся, вам не пришлось бы беспокоиться ни о чем подобном. Но если документация противоречит реальному программному обеспечению, вы можете бесконечно долго выяснять, какая часть является истиной. Является ли это ошибкой? Это недокументированная функция? Это случайный коммит, который проскользнул через обзор кода? Или это просто забытая часть программного обеспечения, которая должна была быть задокументирована в первую очередь, но на нее не обратили внимания.

Все, что я пытаюсь сказать, — это убедиться, что вы учитываете то, что документируете, и планируете время на обслуживание при каждом изменении программного обеспечения!

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

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

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

Заключение

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

1. Опустить документацию

Отказаться от документации en и сделать все либо самодокументируемым (в случае SDK/кодовых файлов), либо интуитивно понятным (в случае SaaS). В обеих ситуациях опыт разработчика/пользователя должен быть на первом месте.

2. Всегда обновляйте документацию соответствующим образом

Пишите правильную документацию и всегда поддерживайте ее в актуальном состоянии. Планируйте время при каждом изменении SDK/продукта, чтобы убедиться, что документация обновлена, и просто никогда не забывайте об этом. Как только вы забыли обновить документацию один раз, легко сделать это чаще, и вы не успеете оглянуться, как ваша документация превратится в динозавра и не поможет вашим пользователям. Это вредит внедрению, производительности и, возможно, даже вашей компании.

Оцените статью
Procodings.ru
Добавить комментарий