Обновить

Документация, которую никто не читает, и документация, которую читают. В чём разница

Работал в командах, где документация была, и где её не было. И в командах, где она была, но не работала. Последнее - хуже всего.

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

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

Разница не в формате и не в инструменте. Разница в том, когда написана и зачем. Полезная документация пишется сразу после того, как разобрался, пока контекст свежий. И для конкретного читателя. Для того, кто столкнётся с этим следующим.

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

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

Обновляйте документацию при каждом изменении кода, включайте это в Definition of Done.

Ежеквартально проверяйте документацию на актуальность, удаляйте устаревшее или лучше архивируйте для сохранения истории.

Пишите понятные заголовки, стабильные якоря и прописывайте единые шаблоны.

Как у вас в команде устроена документация, которая реально используется?

Теги:
Всего голосов 5: ↑5 и ↓0+7
Комментарии0

Записки из подполья незаконного архивирования фильмов

«Люди, видоизменяющие или уничтожающие художественные работы и наше культурное наследие ради прибылей или демонстрации власти — это варвары, и если законы США продолжат оправдывать такое поведение, то мы точно войдём в историю, как варварское общество.»

— Джордж Лукас, 1988 год

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

— Джордж Лукас, 2004 год

Ванкувер, 2011 год: мы с моей соседкой Виллой Росс сидим в одной из характерно стерильных монтажных студий Университета Саймона Фрейзера и уже не знаем, что делать: мы провели все выходные, ваяя из трёх разных копий вестерна Серджо Леоне 1966 года «Хороший, плохой, злой» одну версию — причём все три копии были незаконными рипами. В начале 2000-х этот фильм пал жертвой «реставрации», выполненной компанией MGM: вырезанные Серджо Леоне сцены были возвращены, увеличив время англоязычной версии с 161 до 179 минут; Клинт Иствуд и Илай Уоллак дублировали недостающие диалоги, а место умершего к тому времени Ли Ван Клифа занял похожий на него голосом дублёр. Монофоническая дорожка была переработана в многоканальный звук с неприятно современными звуками выстрелов. Почти десяток лет эта «дополненная» лента оставалась единственной продаваемой версией фильма; подобное очень часто происходит в эпоху ревизионистских студийных реставраций.

Наша цель была простой: спасти фильм от этой вивисекции. Мы планировали соединить звук уже не издававшегося DVD 1998 года (приблизительно похожий на звук международного релиза 1967 года) с видео из недавно привезённого Blu-ray итальянской версии. После того, как мы успешно преодолели многочисленные подводные камни, связанные с риппингом домашних видеозаписей конца 2000-х, наши надежды рухнули из-за катастрофического открытия: итальянская версия оказалась ещё сильнее отличающейся от международной, чем расширенная версия: печально известная сцена пытки была полностью перестроена, а у некоторых кадров отсутствовали начало и конец. Мы почти на десяток лет отказались от этой затеи.

Записки из подполья незаконного архивирования фильмов

Публикации