Документация и сохранение истории процесса, или „Почему этого сделано не будет“

В программных (да и в любых вообще) проектах стоит вести несколько параллельных потоков логов.

  • Первый и главный — это собственно изменения, которые происходят в проекте по мере развития, changelog.
  • Второй — это растущий список возможностей, feature list, сформированный из очищенного и отрефакторенного changelog.
  • Третий — это список замеченных слабостей системы, как идеологических, так и технических („мы не можем решить эту задачу потому-то, хотя это бы могло изменить судьбу человечества“).
  • Четвёртый — это список пожеланий (иногда приводящий к хроническому creeping featuritis), которые обсуждаются и постепенно переезжают в feature list.
  • И, наконец, пятый — „список несбывшегося“, или описание того, какие возможности ещё можно было бы добавить в систему, но почему это сделано не было.

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

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

 project_management
 documentation_writing
 log_everything
 knowledge_management

Об этом по-своему писал [info]behrk:

«

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

»


Из записи „микродокументы как вирусы и утонувшая гравитация“
(18 декабря 2003)


Комментарии (3)

demiurg

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

:: urbansheep

Да, верно. И это и есть, по-моему, расширение „flaw-list“, то есть, если проект большой — нужно разделить одно и другое, flaw не исправляются, а считаются „известными проблемами“ (known issues), а bogus-list становится списком задач второй очереди.

let's rock'n'roll. я засну часа на два. не нужно на меня ругацца, я не помню тот синтаксис.