Как избежать неполных изменений в документации?

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

Вот методы, которые я использовал для поиска и исправления отсутствующих обновлений:

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

• Если функция (функция API, элемент GUI, элемент схемы и т. д.) была изменена или удалена, я ищу в документации соответствующие ключевые слова, такие как имя функции/элемента (однако мы говорим об этом в документации). Это помогает найти случайные ссылки, такие как документация какой-либо другой функции, которая сравнивает ее с той, которая изменилась. Это помогло мне уловить такие случаи, как «Функция X делает бла-бла-бла; она похожа на функцию Y, за исключением ...», где Y изменился.

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

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

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

• В духе «не повторяйтесь» (DRY), если мне нужно включить одну и ту же информацию более чем в одно место, я пытаюсь абстрагировать ее в один блок, который я могу включить по ссылке во всех необходимых местах. идти. Писать фрагментированную документацию, подобную этой, сложнее (вы должны быть осторожны, чтобы убедиться, что ваш большой двоичный объект остается действительным во всех контекстах), но, по моему опыту , такого уровня повторения не происходит . Но это случается иногда, поэтому используйте include tools, когда это произойдет.

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

• Я еще не сделал это в «производстве» (только в качестве теста), но аннотирую ваши скриншоты .

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

• Будьте более тщательны в первоначальной оценке проекта. В начале цикла планирования релиза, когда менеджер по продукту, команда разработчиков и другие планируют предстоящую работу, вы, вероятно, — если вы похожи на большинство людей — добавили в план проекта строку, которая сказал что-то вроде «обновить документ (N недель)». Но если вы сделаете немного больше заранее, вы сможете избежать некоторых проблем для себя и для тестировщиков. ¹Пока разработчики анализируют, что изменится, если они сделают то-то и то-то, вы можете сделать то же самое с документом. Таким образом, вместо этой строки «обновить документ» у вас могут быть такие элементы, как «задокументировать новую функцию X», «обновить функцию Y (которая изменилась из-за X)», «обновить документ примера, который использует Y и Z» и «просмотреть документ». Y для удара». Пока вы разговариваете об этом со своим дружелюбным тестировщиком, вы можете узнать, что ваш тестер знает, что какая-то часть Z тоже должна измениться, поэтому вы можете начать думать об этом раньше. Другими словами, чем больше ваша команда говорит о воздействии на раннем этапе, тем легче вам будет вносить изменения в документ систематически и с меньшей паникой в ​​конце.

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

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

Это намек на решение. Спросите себя: «Для кого предназначена документация?» Должны ли программисты общаться с другими программистами в вашей организации? Затем сделайте все возможное, чтобы сделать код ясным, кратким, неудивительным и СУХИМ. DRY больше о будущем, чем о настоящем.

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

Это для руководителя программы? Затем постарайтесь написать документацию, которая будет ясной, лаконичной и не будет прятаться за техническими модными словечками и псевдоюридическим языком. Большинство людей не следят за документацией, потому что им трудно понять то, что уже написано, трудно подражать стилю и презирают надуманную работу. Нет смысла помещать мельчайшие технические детали в документацию. В противном случае мы бы разработали язык программирования, использующий документы MS Word в качестве исходных файлов.

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

Как правило, это проблема всех частей системы: насколько близко расположены сильно связанные компоненты? Вы увидите, как это происходит в определениях схемы базы данных, если вы управляете ими с помощью необработанных сценариев SQL. Это произойдет с отчетами, сгенерированными в вашей системе, если код отчета находится «далеко» от пользовательского интерфейса отчета. Сохранение связанных частей системы вместе — это единственный способ избежать их дрейфа, подобно некоторым двум образцам вида, которые со временем расходятся после того, как их разделяет океан.

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

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