Кажется, есть отвращение к написанию даже самой базовой документации. Наш проект README относительно голый. В документах нет даже обновленных списков зависимостей.
Есть ли что-то, чего я не знаю в индустрии, что заставляет программистов не любить писать документацию? Я могу напечатать абзацы документов, если это необходимо, так почему другие так не любят это?
Что еще более важно, как я могу убедить их, что написание документов сэкономит нам время и разочарование в будущем?
documentation
teamwork
Рудольф Олах
источник
источник
Ответы:
Я не думаю, что полезно размышлять о мотивах людей, которые не принимают то, что вы считаете хорошей практикой, или которые продолжают делать то, что вы считаете плохой практикой. В этом бизнесе люди, попадающие в одну или обе эти категории, будут намного превосходить по численности те, с которыми вы будете встречаться лицом к лицу, поэтому перестаньте сводить с ума.
Вместо этого сосредоточьтесь на проблеме и возможных решениях.
1. Пишите хорошую документацию самостоятельно
Возможно, нереально ожидать, что все в вашей команде направят свои усилия на то, что вы считаете проблемой. Это особенно верно, если вы относительный новичок в команде. Рискну предположить, что это так, потому что если бы вы были одним из основателей команды, вполне вероятно, что вы уже решили эту проблему на раннем этапе.
Вместо этого подумайте над тем, чтобы самим написать хорошую документацию и заставить ее пользоваться. Например, если кто-то из моей команды спрашивает меня, где находится исходный код для проекта A или какая специальная конфигурация требуется для проекта A, я указываю их на вики-страницу Project A.
Если кто-то спросит меня, как написать новую реализацию Factory F, чтобы настроить что-то для Клиента C, я отвечу, что это на странице 10 руководства разработчика.
Большинство разработчиков ненавидят задавать вопросы, которые могут заставить их выглядеть так, как будто они не могут просто «прочитать код» даже больше, чем они ненавидят чтение документации, поэтому после достаточного количества ответов такого рода они сначала пойдут в документы.
2. Докажите ценность вашей документации
Убедитесь, что вы пользуетесь любой возможностью, чтобы указать, где документация доказывает свою ценность (или имела бы, если бы использовалась). Постарайтесь быть осторожными и избегайте «я же вам говорил», но совершенно справедливо говорить такие вещи, как
или же
3. Получить управление на борту
После нескольких инцидентов, когда наличие документации значительно экономит время и деньги, вы, вероятно, заметите явную «оттепель» в отношении документации. Настало время нажать на точку, начав включать в ваши оценки время документирования (хотя, честно говоря, я обычно обновляю / создаю документы, пока выполняются длинные процессы, такие как компиляции или проверки). Особенно, если это недавний найм, возможно, это не будет подвергаться сомнению, но вместо этого рассматривается как новая практика, которую вы привносите с предыдущего рабочего места (что вполне может быть).
Слово предостережения: большинству боссов не нравится заставлять людей делать что-либо, особенно вещи, не связанные напрямую с оплачиваемой задачей, поэтому не ожидайте, что эта поддержка будет в форме мандата. Вместо этого, скорее всего, у вас будет относительно свободная возможность написать больше документов.
4. Поощряйте документацию, когда вы ее видите
Возможно, одна из причин, по которой люди не пишут документы так часто, как следовало бы, заключается в том, что они чувствуют, что никто не читает их. Поэтому, когда вы видите что-то, что вам нравится, обязательно упомяните, что вы были рады, что это было доступно.
Если ваша команда делает обзоры кода, это время, когда вы можете добавить несколько слов, чтобы получить хорошие комментарии.
Если в вашей команде есть кто-то, кто действительно увлечен документацией, это не помешает развить этого человека за счет того, что он пойдет на обед или кофе и обязательно предложит небольшую проверку, чтобы противостоять разочарованию, которое они могут получить от встречи с остальной частью команды. не так сильно ценит документацию
Кроме того, это действительно не ваша проблема, если вы не занимаетесь лидирующей или управленческой должностью. Вы можете привести лошадь к воде, но вы не можете заставить ее пить. Если это не ваша лошадь, вы не можете быть счастливы, что она хочет пить, но все, что вы можете сделать, это заполнить кормушку.
источник
В моем опыте есть два основных фактора:
Сроки выполнения
Большинство компаний настолько ориентированы на дату, что QA, технологический долг и фактический дизайн сокращаются просто для того, чтобы менеджер проекта не выглядел плохо или не выбрал какой-то абсурдный, слишком обещанный срок для клиента. В этой среде, где снижается даже функциональное качество, у долгосрочных инвестиций, таких как документация, мало шансов.
+ Изменить
Относительно новая лучшая практика для разработчиков - не подчеркивать комментарии. Идея состоит в том, что хранение информации в двух местах (код [включая тесты] и комментарии вокруг кода) приводит к большим накладным расходам на их синхронизацию для небольшой выгоды. «Если ваш код так трудно читать, что вам нужны комментарии, не лучше ли потратить время на его очистку?»
Я лично даже не буду смотреть на комментарии больше. Код не может лгать.
Документация следует в том же духе. С широким распространением Agile люди признают, что требования меняются регулярно. При широком распространении рефакторинга организация кода будет существенно изменяться. Зачем тратить время на документирование всего этого, что обязательно изменится? Код и тесты должны выполнять эту работу достаточно хорошо.
источник
Здесь есть ряд факторов:
Хорошо написанный код - это собственная документация. При прочих равных условиях лучше написать более понятный код, который говорит сам за себя, а не документацию. Сделайте это, и вам нужно будет изменить меньше документации при изменении этого кода.
Написание документации, возможно, отличается от навыков написания кода. Некоторые разработчики программного обеспечения лучше, чем другие. Некоторые гораздо лучше пишут код, чем пишут документацию.
Документация должна быть написана только один раз , а не дважды (один раз в исходном коде и снова в руководстве программиста). Вот почему у нас есть такие вещи, как XML-комментарии и генераторы документации. К сожалению, использование таких инструментов может быть более сложным и обременительным, чем просто написание документации вручную, поэтому вы не видите этих инструментов широко используемыми.
Хорошая документация требует много времени, и ее трудно сделать хорошо. При прочих равных условиях, создание нового кода может иметь большую ценность, чем написание документации для уже существующего кода.
Когда код изменяется, вы также должны изменить документацию. Чем меньше документации, тем меньше ее нужно менять.
В любом случае, никто не читает документацию, так зачем?
источник
Слон в комнате: программисты не (обязательно) писатели. Они также не обязательно поддаются реализации своих технических писателей. Второй слон в комнате: технические писатели, как правило, не в состоянии раскрыть детали, полезные для будущих разработчиков (даже если разработчики соизволят объяснить их им).
Сложная система может стать почти непостижимой со временем без надлежащей документации. Код становится менее ценным обратно пропорционально его чистоте [sic]. Решено, что руководство нанимает инженера-программиста, который может считывать код и информацию от разработчиков, платит ему по ставке разработчика и поручает ему документировать и вести документацию. Этот писатель может читать код и будет знать, какие вопросы задавать, и будет заполнять детали по мере необходимости. Так же, как у вас есть отдел QA, у вас есть внутренний отдел документации.
Код станет более ценным, так как вы можете лицензировать его третьему лицу (потому что он может это понять), код будет легче проверяться и улучшаться / повторно анализироваться, вы будете иметь лучшее повторное использование кода даже там, где вы можете легко Выделите более легкие версии вашего программного обеспечения, и вы сможете легче вводить новых разработчиков в проект, ваши инженеры поддержки будут любить работать на вас.
Это никогда не случится.
источник
Это делает это?
Существует два типа документации:
Полезная документация
Документы о том, как использовать готовый продукт, API, какие IP-адреса или URL-адреса у наших серверов и т. Д. В основном все, что используется интенсивно и ежедневно. Неправильная информация будет быстро обнаружена и исправлена. Нужно найти легко и легко редактировать (например, онлайн-вики).
Бесполезная документация
Документация, которая часто меняется, мало кто интересуется ею, и никто не знает, где ее найти. Как текущее состояние реализуемой функции. Или документы с требованиями в слове doc, спрятанные где-то в SVN, обновленные 3 года назад Эта документация займет время, чтобы написать, и время, чтобы узнать, что это неправильно позже. Вы не можете полагаться на этот тип документации. Это бесполезно. Это пустая трата времени.
Программисты не любят писать или читать бесполезную документацию. Но если вы сможете показать им полезную документацию, они напишут ее. Мы достигли успеха в моем последнем проекте, когда представили вики, где мы могли бы часто записывать всю необходимую нам информацию.
источник
Я бы сказал, что основная причина - это недостаток воли и непонимание функций документации. Существует несколько классов документации, которые следует учитывать:
Документация по продукту / выпуску
Это все, что выходит с вашим «готовым» продуктом. Это больше, чем просто руководства, это READMEs, журналы изменений, HOW-TOs и тому подобное. Теоретически, вы можете не писать, но в итоге вы получите продукт, который люди не хотят использовать, или бремя поддержки, которое излишне дорого обходится.
Документация по API
Это описывает что-то, что должно быть относительно статичным. Поскольку многочисленные пользователи могут кодировать ваш API, он должен быть достаточно стабильным, чтобы некоторая проза, описывающая, как его использовать, имела ценность. Описание поддерживаемых параметров, возможного возвращаемого значения и возможных ошибок позволит другим пользователям понять ваш API на правильном уровне абстракции - интерфейсе (а не реализации).
Комментарии к коду
На данный момент мнение отрасли о комментариях меняется. Когда я впервые начал профессионально программировать, комментарии были непременным условием написания кода. Теперь модно писать код, который настолько понятен, комментарии не нужны. Я бы рискнул предположить, что это отчасти из-за того, что многие современные языки написаны на гораздо более высоком уровне, и гораздо проще писать разборчивый код на Java, JavaScript, Ruby и т. Д., Чем это было на ассемблере. , C, FORTRAN и т. Д. Таким образом, комментарии имели гораздо большее значение.
Я по-прежнему считаю, что в комментариях есть ценность, описывающая намерение фрагмента кода, или некоторые подробности о том, почему определенный алгоритм был выбран вместо более очевидного (чтобы избежать чрезмерного усердия в рефакторинге из-за «исправления» кода, который не т на самом деле нужно исправить).
К сожалению, есть много эгоизма, рационализации и самообмана, связанных с решениями программистов не документировать. Реальность такова, что, как и код, основная аудитория документации - это другие люди. Таким образом, решения о написании (или не написании) документации на любом уровне должны приниматься на уровне команды. Для более высоких уровней абстракции может иметь больше смысла, чтобы кто-то, кроме разработчиков, делал это. Что касается документации на уровне комментариев, то достижение соглашения о цели и намерении комментариев должно быть согласовано вместе, особенно в группах со смешанными способностями и опытом. Плохо, когда старшие разработчики пишут код, к которому не могут обратиться младшие разработчики. Некоторые хорошо поставленные и хорошо написанные документы могут позволить команде работать намного эффективнее
источник
Вот мои два цента.
Agile Manifesto гласит: «Работа над программным обеспечением над исчерпывающей документацией», и далеко не все читают, чтобы достичь: «То есть, хотя элементы справа имеют ценность, мы ценим элементы слева больше».
К сожалению, это характерно для https://en.wikipedia.org/wiki/Code_and_fix, и документация не работает с этой моделью (она не синхронизирована).
Индустрия разработки программного обеспечения плохо регулируется. Нет юридических требований для написания документации.
Самодокументированный код - актуальная тенденция.
Сказав это, я думаю, что есть много хорошей документации там.
источник
Документация требует времени, и я подозреваю, что у многих разработчиков было слишком много запусков с документацией, которая была хуже, чем бесполезна. Они понимают, что не только документирование доставит им неприятности от их менеджера (того же самого парня, который продолжает сокращать часть контроля качества), но это никому не поможет, включая их.
Любая полуприличная часть документации - это инвестиции в будущее. Если вас не волнует будущее (потому что вы не думаете о следующей зарплате или думаете, что это не будет вашей проблемой), тогда мысль о создании документации чрезвычайно болезненна.
источник
Во многих других ответах подчеркивается, что существует как минимум два типа документации: один для других разработчиков и другой для конечных пользователей. В зависимости от вашей среды, вам также может понадобиться дополнительная документация для системных администраторов, установщиков и сотрудников службы поддержки. У каждой целевой аудитории разные потребности и уровни понимания.
Рассмотрим типичного (стерео) разработчика: он по выбору кодер. Он выбрал карьеру вне поля зрения общественности и проводит долгие часы за клавиатурой, общаясь в основном с самим собой. Процесс документирования - это форма общения, и набор навыков, необходимых для создания хорошей документации, противоречит навыкам, необходимым для создания хорошего кода.
Хороший писатель документации может общаться на нескольких языках: языке пользователей, языке управления, языке обслуживающего персонала, языке разработчиков. Работа автора документации заключается в том, чтобы понять, что сообщает программист, и перевести это в форму, понятную для всех других групп.
Когда вы ожидаете, что программисты приобретут навыки, необходимые для того, чтобы стать хорошими коммуникаторами (написанными или нет), количество времени, затрачиваемого на оттачивание основного набора навыков (кодирование!), Уменьшается. Чем дальше он добирается из своей зоны комфорта (кодирование и общение с другими программистами), тем больше времени и энергии потребуется для хорошего выполнения задачи. Вы можете разумно ожидать, что профессиональный кодировщик захочет сосредоточиться, прежде всего, на своей основной компетенции, за счет всех остальных.
По этой причине документацию (за исключением комментариев встроенного кода) лучше оставить коммуникаторам, а не программистам.
источник
Чтение кода покажет вам, как это работает. Это не может объяснить почему : вам нужны комментарии.
Чтение кода покажет вам имя метода и типы параметров. Он не может объяснить семантику или точное намерение автора: вам нужны комментарии.
Комментарии не заменяют чтение кода, они добавляют к нему.
источник
Документация не выполняется как код. В результате часто возникают неэффективные петли обратной связи для проверки того, что документация имеется и является полной. Это та же самая причина, по которой комментарии кода имеют тенденцию гнить.
Дональд Кнут продвигал « Литературное программирование» как способ повышения качества программного обеспечения, эффективно сочиняя документацию с помощью кода. Я видел несколько проектов, которые достаточно эффективно использовали этот подход.
Лично я стараюсь придерживаться современной тенденции, заключающейся в том, чтобы сделать публичный API вашего кода как можно более читабельным, и использовать модульные тесты для документирования использования другими разработчиками. Я думаю, что это часть большей идеи, чтобы ваш API имел форму, которую можно исследовать и открывать. Я думаю, что этот подход является частью того, что HATEOAS пытается достичь с помощью веб-сервисов.
источник
Незначительный момент, но тот, который кажется важным для некоторых разработчиков, которые пишут неприятно мало документации: они не могут печатать. Если у вас есть приблизительное представление о системе из 10 пальцев, вы склонны писать больше документации только потому, что это легко. Но если вы застряли на охоте и клюете, вы потерялись. Если бы я был ответственным за наем, это на самом деле то, что я бы проверить.
источник
Люди, которые не любят читать документацию, не любят писать документацию. Многие программисты сделают все возможное, чтобы не читать документ полностью.
Не сосредотачивайтесь на письме, сосредоточьтесь на чтении. Когда программисты читают документацию и усваивают из нее что-то, они видят ценность и гораздо больше склонны ее писать.
источник
Когда я начал свою текущую работу и взял на себя проект аппаратного обеспечения и программного обеспечения от людей, которые ранее работали над ним, мне дали документ в сто с лишним страниц, описывающий систему. Должно быть, потребовались дни, чтобы произвести. Я посмотрел на это, может быть, дважды. Несмотря на огромное количество информации, он редко отвечал на реальные вопросы о системе, которые у меня были, и даже когда это происходило, смотреть на код было быстрее.
После достаточного количества подобных опытов вы просто начинаете думать, зачем? Зачем тратить время на ответы на вопросы, которые люди никогда не задавали? Вы начинаете понимать, насколько трудно предсказать, какую информацию люди будут искать в документации; оно неизбежно наполнено фактами, которые оказываются бесполезными, неясными или очевидными, и в них отсутствуют ответы на самые насущные вопросы. Помните, что создание полезной документации - это попытка предсказать поведение человека. Подобно тому, как дизайн пользовательского интерфейса вряд ли будет успешным до того, как он пройдет несколько итераций тестирования и отладки, наивно думать, что можно написать полезную документацию, основанную только на ожиданиях того, как люди будут интерпретировать систему, и что роль в этой интерпретации будет играть документация и ее язык.
Я склонен думать, что большая часть давления на написание документации проистекает из того факта, что это неприятная рутинная работа, и людям нравится заставлять друг друга делать неприятные рутинные работы («Вы не ели свою червоточину!»).
ТЕМ НЕ МЕНИЕ
Я не думаю, что документация во всех отношениях безнадежна. Я думаю, что это безнадежно, прежде всего, когда люди смотрят на документацию как на дополнительное бремя, которое должно быть выполнено до завершения работы, как на последний кусок работы по очистке, которую нужно поторопить, и как на флажок, который нужно проверить. Документация - это то, что вы должны работать в аспектах своего дня, которые вы всегда делаете в любом случае. Я думаю, что электронная почта - особенно хороший способ сделать документацию. Когда вы добавляете новую функцию, напишите нескольким людям быстрое электронное письмо, в котором говорится, что это такое. Когда нарисуете новую схему, создайте PDF и отправьте его всем, кто может быть заинтересован. Преимущества электронной почты:
Люди обычно проверяют электронную почту, в то время как никто не просматривает папку с именем «doc».
Электронная почта существует в контексте, окружена другими электронными письмами, в которых обсуждается функция и связанные с ней функции, а также все остальное, что происходило в то время.
Электронная почта короткая и сфокусированная и имеет тему.
Электронная почта позволяет людям, которые хотят сразу же задать вопросы,
Электронная почта хорошо подходит для поиска, потому что люди используют ее для всего, и почтовые клиенты значительно продвинулись за эти годы.
Если оно есть в электронном письме, то хотя бы один человек знает, где его найти.
Теоретически может показаться, что комментарии в коде также должны быть «аспектами вашего дня, которые вы всегда делаете в любом случае», но, если честно, я никогда не читаю комментарии в коде. Я не уверен, почему, но они просто не очень полезны, возможно, из-за недостатка контекста, который решает электронная почта.
источник