Что с отвращением к документации в отрасли?

47

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

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

Что еще более важно, как я могу убедить их, что написание документов сэкономит нам время и разочарование в будущем?

Рудольф Олах
источник
13
Потому что мы знаем, что делаем! Почему мы должны не торопиться, чтобы записать то, что мы уже знаем и никогда не забудем!?!? Если серьезно, я ежедневно занимаюсь этим же, работая над базой кода, которая начала процесс проектирования 7 лет назад и с тех пор ежедневно обновляется командой из 4-7 инженеров. Документация - это то, с чем мы всегда боролись, но это неизбежное зло.
День
62
Потому что опыт доказал, что никто не читает документы.
user16764
8
С точки зрения бизнеса множество документов стоит компании здесь и сейчас, когда вы могли бы вместо этого работать над следующим проектом, чтобы заработать деньги. То, что вы всегда должны приносить прибыль, - это давление, которое вы испытываете против «траты времени» на написание документации. Кроме того, никто никогда не читает документы, а читает источники, потому что только они являются высшим авторитетом.
Патрик Хьюз
15
Синхронизация документов с последним кодом может быть «сложной», если вы пишете на более высоком уровне, чем Javadoc или эквивалентный.
Дэн Пичельман,
12
Это не весело ...

Ответы:

21

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

Вместо этого сосредоточьтесь на проблеме и возможных решениях.

1. Пишите хорошую документацию самостоятельно

Возможно, нереально ожидать, что все в вашей команде направят свои усилия на то, что вы считаете проблемой. Это особенно верно, если вы относительный новичок в команде. Рискну предположить, что это так, потому что если бы вы были одним из основателей команды, вполне вероятно, что вы уже решили эту проблему на раннем этапе.

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

Если кто-то спросит меня, как написать новую реализацию Factory F, чтобы настроить что-то для Клиента C, я отвечу, что это на странице 10 руководства разработчика.

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

2. Докажите ценность вашей документации

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

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

или же

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

3. Получить управление на борту

После нескольких инцидентов, когда наличие документации значительно экономит время и деньги, вы, вероятно, заметите явную «оттепель» в отношении документации. Настало время нажать на точку, начав включать в ваши оценки время документирования (хотя, честно говоря, я обычно обновляю / создаю документы, пока выполняются длинные процессы, такие как компиляции или проверки). Особенно, если это недавний найм, возможно, это не будет подвергаться сомнению, но вместо этого рассматривается как новая практика, которую вы привносите с предыдущего рабочего места (что вполне может быть).

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

4. Поощряйте документацию, когда вы ее видите

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

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

Спасибо за документирование обходного пути для ошибки B в Framework G. Я не знал об этом, и я не думаю, что мог бы понять, что вы делали без этого там.

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

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

Эми Бланкеншип
источник
1
+1 за пункт № 2, прямо отвечая на вопрос ОП, который начинается с «Как мне убедить…»
Рэй Тоал
Мне нравится этот ответ, остальные больше сосредоточились на «почему», а не на «как»
Рудольф Олах
@omouse - потому что в большинстве случаев написание документации не сэкономит ваше время и разочарование в будущем. Они редко точны, и люди никогда не читают их, даже когда они есть.
Теластин
1
Принципы SOLID обычно не экономят ваше время и не приводят к лучшему дизайну, потому что большинство людей либо не до конца их понимают, либо на самом деле не дают дерьма. По вашей логике мы не должны стремиться применять их, GRASP или любые другие хорошие практики. Напомни мне, почему ты снова пытаешься участвовать в программировании?
Эми Бланкеншип
Это очень полезно для размышлений о мотивации людей.
тымтам
55

В моем опыте есть два основных фактора:

Сроки выполнения

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

+ Изменить

Относительно новая лучшая практика для разработчиков - не подчеркивать комментарии. Идея состоит в том, что хранение информации в двух местах (код [включая тесты] и комментарии вокруг кода) приводит к большим накладным расходам на их синхронизацию для небольшой выгоды. «Если ваш код так трудно читать, что вам нужны комментарии, не лучше ли потратить время на его очистку?»

Я лично даже не буду смотреть на комментарии больше. Код не может лгать.

Документация следует в том же духе. С широким распространением Agile люди признают, что требования меняются регулярно. При широком распространении рефакторинга организация кода будет существенно изменяться. Зачем тратить время на документирование всего этого, что обязательно изменится? Код и тесты должны выполнять эту работу достаточно хорошо.

Telastyn
источник
11
+1 за «лично я даже не буду смотреть на комментарии», я думаю, что это часто встречается; когда вы достигаете определенного уровня комфорта с помощью самого кода, вы можете читать его быстрее, чем комментарии (и еще быстрее, если комментарии не мешают), и код не лжет
Джимми Хоффа
41
Это пропускает точку комментариев, которая объясняет почему . Они не должны быть повсюду, и они не должны быть очень длинными, но хорошо размещенная ссылка на бизнес-правила, описывающие, почему следующие 20 строк действительно странной логики существуют в его текущем состоянии, намного больше удобнее, чем пытаться пролистать историю версий, чтобы найти оригинальное обоснование.
zzzzBov
7
@zzzzBov - безусловно, это современный взгляд на вещи. Это изменилось по сравнению с предыдущими точками зрения, которые поощряли более широкое комментирование. Аналогично, документация о том, что делает код, сократилась до документации, которая фокусируется на том, почему он делает это (например, дизайн документации).
Теластин
8
Код может лгать. Клиент, возможно, хотел чего-то, и это было закодировано, чтобы сделать что-то еще. Так что, если все, что у вас сейчас есть, это код, это правильно?
thursdaysgeek
6
Код может лгать ... У меня есть метод из 4000 строк (эй, я его не создавал, я им сейчас владею ...), и я вижу коллекцию с четким названием productList, поэтому для нового изменения я добавляю продукт возражать против этого. Отлично. Только это не работает, оказывается, что какой-то прошлый разработчик был «эффективным» и повторно использовал переменную типа List, чтобы избежать загромождения 4000 строк слишком большим количеством переменных, и в этой области он содержит объекты Customer ...
Кевин Рубин
17

Здесь есть ряд факторов:

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

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

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

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

  5. Когда код изменяется, вы также должны изменить документацию. Чем меньше документации, тем меньше ее нужно менять.

  6. В любом случае, никто не читает документацию, так зачем?

Роберт Харви
источник
2
№ 1, я не думаю, что это когда-либо так, но № 4 определенно верно
Рудольф Олах
3
@whatsisname: совсем нет. Напишите более понятный код, который требует меньше документации, и вам нужно будет изменить меньше документации при изменении этого кода.
Роберт Харви
2
@thursdaysgeek: Эти маркеры означают, что вам не нужно писать документацию дважды: один раз для комментариев к коду и еще раз для справочного файла / справки программиста. Вы, конечно, не должны переписывать это дважды. Ребята, вы читаете эту вещь?
Роберт Харви
4
# 6 ... Я думаю, что это распространенное заблуждение. Много людей читают документацию тщательно.
Динамичный
3
@tymek: Вы получили свой знак задом наперед. Ребята, это не учебник о том, как создавать документацию; это расчет того, почему разработчики относятся к этому негативно.
Роберт Харви
11

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

Сложная система может стать почти непостижимой со временем без надлежащей документации. Код становится менее ценным обратно пропорционально его чистоте [sic]. Решено, что руководство нанимает инженера-программиста, который может считывать код и информацию от разработчиков, платит ему по ставке разработчика и поручает ему документировать и вести документацию. Этот писатель может читать код и будет знать, какие вопросы задавать, и будет заполнять детали по мере необходимости. Так же, как у вас есть отдел QA, у вас есть внутренний отдел документации.

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

Это никогда не случится.

naftalimich
источник
1
Не говоря уже о том, что при попытке описать существующий код становится сложнее дать хорошее описание, когда код и функциональность настолько сложны, что никто не знает, что он уже делает, поэтому любые новые изменения оказывают влияние, которого новый разработчик не сделал знать о ...
Кевин Рубин
1
Я бы предположил, что «базовая способность сообщать о своих намерениях (ограниченной) документации» является необходимым навыком программиста. Программисту не обязательно быть поэтом, но если он или она не может документировать, я, честно говоря, не хочу, чтобы он был в моей команде. Такой человек несет долгосрочную ответственность.
5

Что еще более важно, как я могу убедить их, что написание документов сэкономит нам время и разочарование в будущем?

Это делает это?

Существует два типа документации:

Полезная документация

Документы о том, как использовать готовый продукт, API, какие IP-адреса или URL-адреса у наших серверов и т. Д. В основном все, что используется интенсивно и ежедневно. Неправильная информация будет быстро обнаружена и исправлена. Нужно найти легко и легко редактировать (например, онлайн-вики).

Бесполезная документация

Документация, которая часто меняется, мало кто интересуется ею, и никто не знает, где ее найти. Как текущее состояние реализуемой функции. Или документы с требованиями в слове doc, спрятанные где-то в SVN, обновленные 3 года назад Эта документация займет время, чтобы написать, и время, чтобы узнать, что это неправильно позже. Вы не можете полагаться на этот тип документации. Это бесполезно. Это пустая трата времени.

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

UOOO
источник
4

Я бы сказал, что основная причина - это недостаток воли и непонимание функций документации. Существует несколько классов документации, которые следует учитывать:

Документация по продукту / выпуску

Это все, что выходит с вашим «готовым» продуктом. Это больше, чем просто руководства, это READMEs, журналы изменений, HOW-TOs и тому подобное. Теоретически, вы можете не писать, но в итоге вы получите продукт, который люди не хотят использовать, или бремя поддержки, которое излишне дорого обходится.

Документация по API

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

Комментарии к коду

На данный момент мнение отрасли о комментариях меняется. Когда я впервые начал профессионально программировать, комментарии были непременным условием написания кода. Теперь модно писать код, который настолько понятен, комментарии не нужны. Я бы рискнул предположить, что это отчасти из-за того, что многие современные языки написаны на гораздо более высоком уровне, и гораздо проще писать разборчивый код на Java, JavaScript, Ruby и т. Д., Чем это было на ассемблере. , C, FORTRAN и т. Д. Таким образом, комментарии имели гораздо большее значение.

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

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

Dancrumb
источник
1
+1 за "основная аудитория для документации это другие люди". Слишком много программистов не очень ценят общение с другими. (Именно поэтому им будет трудно продвигаться по старшинству.)
Донал Феллоуз
4

Вот мои два цента.

  1. Agile Manifesto гласит: «Работа над программным обеспечением над исчерпывающей документацией», и далеко не все читают, чтобы достичь: «То есть, хотя элементы справа имеют ценность, мы ценим элементы слева больше».

  2. К сожалению, это характерно для https://en.wikipedia.org/wiki/Code_and_fix, и документация не работает с этой моделью (она не синхронизирована).

  3. Индустрия разработки программного обеспечения плохо регулируется. Нет юридических требований для написания документации.

  4. Самодокументированный код - актуальная тенденция.

Сказав это, я думаю, что есть много хорошей документации там.

tymtam
источник
(1) « Мы ценим вещи слева больше ... » не означает, что мы вообще не заботимся о правой стороне. (2) « 4. Самостоятельно документирующий код является современной тенденцией ». Если документация не нужна, тогда почему люди в первую очередь жалуются на плохую / недостающую документацию? (3) Время, которое один разработчик экономит, не документируя свою работу, тратится каждым разработчиком, которому нужна информация, потому что он должен отсканировать 5000 строк самодокументируемого кода вместо документации на 5 страниц. Эффективность - это что-то еще, но эй, мы проворные!
JensG
2

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

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

Майкл Кохне
источник
2

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

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

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

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

По этой причине документацию (за исключением комментариев встроенного кода) лучше оставить коммуникаторам, а не программистам.

Джордж Камминс
источник
4
О, пис. Чем больше вы научитесь делать хорошо, тем лучше вы научитесь делать вещи хорошо. Так же, как люди, которые знают несколько языков, программируют лучше, чем люди, которые знают только один (потому что они знают больше способов думать о проблеме), способность писать и даже визуализировать графически дает вам больше инструментов, чтобы думать и решать проблемы. Навыки, которые вам нужны, чтобы уметь описывать происходящее, - это те же навыки, которые вам нужны, чтобы понять, что должно произойти.
Эми Бланкеншип
1
Я хочу, чтобы другие разработчики были или стали опытными коммуникаторами. Подавляющее большинство программ, которые мы делаем (по крайней мере, в программном обеспечении для бизнеса), не требуют абсолютного наивысшего набора навыков кодирования. Это требует намного лучших навыков общения между людьми, чтобы будущие разработчики понимали, что было написано. Чем лучше разработчик сможет общаться, особенно с людьми, с которыми он никогда не встретится, тем лучше он будет восприниматься в долгосрочной перспективе, и вряд ли для умного кода.
Кевин Рубин
2

Чтение кода покажет вам, как это работает. Это не может объяснить почему : вам нужны комментарии.

Чтение кода покажет вам имя метода и типы параметров. Он не может объяснить семантику или точное намерение автора: вам нужны комментарии.

Комментарии не заменяют чтение кода, они добавляют к нему.

benlast
источник
4
+1 за настроение. Но это не ответ на вопрос; Вы, кажется, отвечаете на что-то еще здесь, кроме фактического вопроса.
bignose
2

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

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

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

aboy021
источник
Чтобы оправдать свой выбор в отношении автоматического создания документации, я придумал формулу, чтобы показать, как человеческая инерция является виновницей всех комментариев. Расширяя этот аргумент, я обнаружил, что создание методов, обеспечивающих реальные преимущества для разработчика, таких как частично автоматическое создание диаграмм из мета-комментариев в исходном коде, имеет тенденцию обновляться каждый раз, когда разработчик пытается разобраться в коде. Кстати, чаще всего этот разработчик просто «будущее меня».
wolfmanx
0

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

Ханс-Петер Стёрр
источник
0

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

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

Джори Себрехтс
источник
-1

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

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

Я склонен думать, что большая часть давления на написание документации проистекает из того факта, что это неприятная рутинная работа, и людям нравится заставлять друг друга делать неприятные рутинные работы («Вы не ели свою червоточину!»).

ТЕМ НЕ МЕНИЕ

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

  1. Люди обычно проверяют электронную почту, в то время как никто не просматривает папку с именем «doc».

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

  3. Электронная почта короткая и сфокусированная и имеет тему.

  4. Электронная почта позволяет людям, которые хотят сразу же задать вопросы,

  5. Электронная почта хорошо подходит для поиска, потому что люди используют ее для всего, и почтовые клиенты значительно продвинулись за эти годы.

  6. Если оно есть в электронном письме, то хотя бы один человек знает, где его найти.

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

Оуэн
источник
кроме # 4 («люди, которые заботятся, сразу задают вопросы»), ни одно из перечисленных вами преимуществ электронной почты не работает для меня надежно. 1: Люди , как правило, игнорируют электронную почту, когда есть много его 2: Email часто имеет тенденцию к потере связи, похоронив его в побочных вопросах и overquoting 3: Электронные письма слишком часто долго / большие и , как правило , теряет фокус , как обсуждение попадет в дополнительные побочные вопросы и сюжеты часто не имеют значения / устарели («Re: WTF произошел сегодня на сервере?») ...
Гнат
... 5: Поиск по электронной почте сильно скомпрометирован из-за способности удалять письма, функция, которую имеет любой приличный почтовик, и любого активного почтового пользователя, использует много 6: см. 5, если почта удалена, никто не сможет найти его (единственное, на что я могу положиться - это поиск в отправленных письмах, и это только потому, что я очень стараюсь не удалять их). Кроме похвалы по электронной почте (что выглядит для меня совершенно неоправданно), вы можете сделать несколько хороших замечаний
комнат
@gnat Полагаю, это может отличаться от компании к компании по поводу удаления. В моей компании мы сохраняем все электронные письма, а также архивы всех электронных писем от прошлых сотрудников, и всякий раз, когда новый человек начинает задачу, мы пересылаем этому человеку все связанные электронные письма. Я полагаю, разница в стиле.
Оуэн
да, это зависит много от стиля / культуры. Хотя «борьба с удалением», безусловно, выполнима (и даже технически легко достижима при экспорте почтовых потоков на какой-либо сервер), такие вещи, как сохранение их целенаправленности, релевантные строки темы, цитирование с ограниченным разумным лимитом, - вещь весьма культурная, требующая значительных усилий и решимость (и поддержка управления) для поддержания ... По сравнению с этими усилиями, и особенно с необходимостью участия в mgmt, поддержка таких вещей, как папки wiki / code comments / doc, может оказаться проще
коммент