Название действительно говорит само за себя.
Иногда это может закончиться тем, что разработчики и ИТ-специалисты ссорятся из-за подобных вещей. Какой уровень документации вы ожидаете при установке, исправлении, обслуживании, запуске, остановке и диагностике решения, работающего на одном или нескольких серверах?
Все это должно быть подробно задокументировано, хотя, когда операция является стандартной для операционной системы, сервера приложений, веб-сервера и т. Д., Вы можете предположить, что сотрудники ИТ-отдела знают, как это делать.
Монтаж: документируйте все о том, как он установлен и настроен, в том числе о том, как определить, правильно ли он работает.
Расскажите нам об архитектуре, особенно о связи между различными компонентами решения (например, диапазон портов - механизмы RPC часто используют диапазон портов - нам нужно знать, каков диапазон и когда у приложения могут закончиться порты).
Патчинг: задокументируйте все, что относится к приложению - что необходимо закрыть перед установкой исправлений, и любые последующие действия после исправления (кеши, индексы, прокси, которые, возможно, потребуется очистить или перестроить).
Обслуживание: задокументируйте, как выглядит нормальная и ненормальная работа - какие очереди и другие вещи следует контролировать и каков их нормальный диапазон.
Расскажите нам, как управлять данными, особенно таблицами и файлами, которые неограниченно растут (например, файлами журналов и историями транзакций). Как их следует очистить и каковы последствия удаления старых записей? (по отчетности и т. д.).
Расскажите нам, как выполнять стандартные действия по обычному ведению дел / повседневные действия - например, добавлять или изменять учетные записи пользователей.
Сообщите нам о любых других регулярных действиях управления, которые могут потребоваться (например, какие сертификаты используются и что делать по истечении срока их действия).
Для всех изменений сообщите нам, как их откатить (не все изменения успешны). И сообщите нам, что вы протестировали планы отката!
Диагноз: Документируйте форматы и расположение файлов журнала, а также КАЖДОЕ сообщение об ошибке приложения, которое может появиться, с указанием, что означает сообщение об ошибке, и что может потребоваться изменить, чтобы исправить это. Никогда не используйте одно и то же сообщение об ошибке для двух разных событий.
Сбили и запустили: Как, в каком порядке, какие-либо особые процедуры (например, позволить серверам истощить соединения перед их отключением).
Я категорически не согласен с тем, что лучший способ сделать это - бросить приложение через забор и позволить ИТ-специалистам решить, что необходимо. Оперативная документация (и в целом возможности управления приложением) должны быть продуманы заранее.
Следующим вопросом будет: что произойдет, если (а не если) разработчики не предоставят достаточную документацию?
Я рекомендую, чтобы ИТ-специалисты имели возможность вводить отчеты о дефектах программного обеспечения, используя любую систему отслеживания дефектов, которую используют разработчики. Таким образом, если они не сказали вам, например, что файлы в определенной папке необходимо очистить и что следует хранить только неделю, вы можете указать дефект, в котором говорится, что «приложение заполняет диск файлами журнала. ", и предложить им поработать с ИТ-отделом над документированным методом очистки этой папки.
Мой список требований к документации будет (не в каком-либо определенном порядке):
(документация :)
Подобная документация - это примеры хорошей документации:
Я считаю, что подобная документация полна ошибок:
Также FreeBSD Handbook - отличный пример документации и подхода OpenBSD. Они выгоняют вещи, которые не документированы должным образом.
РЕДАКТИРОВАТЬ: этот список ни в коем случае не является полным, это просто основные вещи это сразу пришло мне в голову. Так же документация должна быть хорошо читаемой, а не просто что-то такое, что читается.
Короче говоря, я рассчитываю на указанную мной документацию и договор.
Слишком часто эта важная деталь упускается из виду. Конечный пользователь этого ожидает и, конечно же, хочет получить это бесплатно. Хорошие разработчики исправят эту оплошность на раннем этапе и установят ожидания, включая требования к цене и времени.
Я считаю, что ИТ-отделам необходимо сообщить разработчикам, какая документация необходима. Лучший способ сделать это - предоставить ИТ-специалистам предварительные версии (или итерационные выпуски) решения для тестирования и тестирования, чтобы ИТ-специалисты могли ответить тем, что необходимо.
Создание адекватных примечаний к выпуску с приложением было бы хорошим началом. Если есть изменения в текущем поведении с выпуском, любые заметки от QA об изменениях зависимостей или поведения запуска / остановки, изменениях нагрузки на зависимые серверы или базы данных и т. Д.
@Spoike (пока не могу комментировать ответы ..)
Разработчики ИТ (роль будет зависеть от типа и размера компании) должны работать последовательно для достижения следующих целей:
Минимальные требования для установки / оборота - другими словами, ИТ-специалисты не могут быть пассивными и ожидать, что разработчики «знают», какая информация необходима во время установки / перехода. Я обнаружил, что в ИТ-отделах часто возникает значительная путаница / разногласия относительно того, что составляет надлежащую документацию приложения. Dev понимает требования (мы надеемся), и ИТ-специалисты должны провести собрание, чтобы найти, как минимум, то, что требуется.
Процедура установки / передачи - в корпоративных настройках вы можете назвать это «Управление изменениями» или «Управление», но по сути это стандартный цикл проверки, в котором ИТ-специалисты устанавливают Dev PRIOR наверху, чтобы получить информацию о продукте и его потребностях.
Установка приложения мало чем отличается от дебюта театральной постановки. Перед тем как подняться занавес, директор (ведущий разработчик) неоднократно встречается с производственной командой (разработчиками ИТ), чтобы убедиться, что все «так» для премьеры (публичная установка).
Вы не можете изменить образ разработчика (зачем вам это нужно?), Но вы можете указать на вашу общую цель - создать фантастическое приложение, которое работает невероятно быстро для всех пользователей. Ваши согласованные требования к ИТ-документации - лишь одна из вещей, необходимых для этого.