Унизительная документация - как с этим бороться?

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

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

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

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

Проблема

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

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

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

На данный момент кажется, что люди знают о проблеме, включая руководителя проекта, но, похоже, никто не обеспокоен тем, чтобы что-то с ней сделать (или есть что-то более интересное).

Моя первоначальная мысль состояла в том, чтобы бросить все это в забвение (после того, как меня укусили устаревшие «советы» несколько раз подряд), но я полагаю, что это может быть слишком экстремальным. Некоторая информация заслуживает внимания и иногда хорошо читается, но проблема все та же: как вы справляетесь с ее «актуальностью» ? Связана ли она с исходным кодом каким-либо образом (поэтому, когда проверяется обновленная версия файла, автор статьи получает уведомление о том, что ему может потребоваться пересмотреть код / ​​статью)? Определил ли человек, "следящий" за этим на ежедневных основах? Регулярные уборки?

Похоже, вы документируете слишком много пустяков в вики.

Документы блоков кода и методы в коде . Постарайтесь сделать свой код самодокументированным, чтобы вам не приходилось много комментировать. Написание модульных тестов тоже может помочь.

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

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

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

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

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

Нередки случаи, когда люди «ожидают» документации по программному обеспечению, если это не так.

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

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

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

мотивы дизайнерских решений для частей API

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

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

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

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

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

Если вы используете язык .net, посмотрите на ( Sandcastle ), который берет документацию XML (/// в C #) и преобразует ее в формат справки MSDN.

Формат включает описание, комментарии и имеет возможность включать примеры кода, а также некоторые другие функции. Вы можете выводить в форматах .CHM, .HsX, .MSCH и HTML / ASP.NET. Фактический проект добавляется в ваше решение и строится на сервере сборки. Мы сделали это и развернули на веб-сайте каждый выпуск, и потребители любят его, потому что документация имеет отношение к выпуску и постоянно обновляется.

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

Это стало единственной документацией, которую мы используем, так как мотивы и особенности использования API могут быть включены в раздел «Комментарии» документации. Процесс работает хорошо там, где я работаю.

Я бы сосредоточился на двух областях: 1) код. 2) Нетексные заметки и документ.

1) код.

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

Вместо такого рода псевдокода:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Сделайте код, который больше похож на это:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

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

2) не код

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