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

Название говорит обо всем на самом деле.

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

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

Установка: документируйте все о том, как он установлен и настроен, включая как узнать, работает ли он правильно.

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

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

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

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

Расскажите нам, как выполнять стандартные действия по управлению «обычным делом» / in-life - например, это может быть добавление или изменение учетных записей пользователей.

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

Для всех изменений сообщите нам, как откатить их (не все изменения успешны). И скажите нам, что вы проверили планы отката!

Диагностика: Документируйте форматы и местоположения файлов журналов и КАЖДОЕ сообщение об ошибке приложения, которое может появиться, сообщая, что означает сообщение об ошибке, и что может потребоваться изменить, чтобы исправить это. Никогда не используйте одно и то же сообщение об ошибке для двух разных событий.

Сбить и запустить: Как, в каком порядке, какие-либо специальные процедуры (например, позволить серверам истощать соединения перед их отключением).

Я категорически не согласен с тем, что лучший способ сделать это - бросить приложение через забор и позволить ИТ-специалистам решить, что нужно. Эксплуатационная документация (и, в общем, особенности управляемости приложения) должна быть продумана заранее.

Следующим вопросом будет: что произойдет, если (не если) разработчики не предоставят достаточную документацию?

Я рекомендую ИТ-отделу иметь возможность вводить отчеты о дефектах в программное обеспечение, используя любую систему отслеживания дефектов, которую используют разработчики. Таким образом, если вам, например, не сказали, что файлы в определенной папке необходимо очистить и что нужно хранить только недельную стоимость, вы можете ввести ошибку, сказав: «приложение заполняет диск файлами журнала. и предложили, чтобы они работали с ИТ на задокументированном методе очистки этой папки.

Мой список требований к документации будет (не в каком-либо конкретном порядке):

(документация по :)

• все ключи командной строки
• все состояния выхода и возвращаемые значения
• регистрировать сообщения (не столько контент, сколько поясняющие поля, если это не настраивается)
• синтаксис конфигурации
• переключатели в конфигурационных файлах
• использование памяти
• это резьбовое или раздвоенное
• на какие сигналы реагирует сервер
  • есть ли сигнал, который не перезагружает сервер, но заставляет его перечитать конфигурацию
  • как оно себя ведет? (Ожидает ли он, когда существующие потоки / процессы завершат работу со старой конфигурацией? Убивает ли их, ...)
• что происходит при нечистом завершении работы (особенно если это какой-то постоянный сервис / сервер)
• регистрирует ли он системные вызовы или регистрирует что-то написанное само по себе ( гадость для apache и access log - я явно предпочитаю встроенные инструменты для регистрации)
• IPv4 и IPv6 готовы, если это сетевой сервис
• документация по транку и документация по конкретной версии
  • ничто не так плохо, как настройка чего-то в течение нескольких часов, просто чтобы узнать, что это будет проигнорировано, потому что опция конфигурации доступна только в транке
• какой параметр конфигурации действителен в какой версии (доступно с версии v1.0, устарело с версии v1.2 или чего-то подобного)

Подобная документация - примеры хорошей документации:

• http://httpd.apache.org/docs/2.2/
• http://www.postgresql.org/docs/8.3/static/index.html

Я бы посчитал документацию, подобную этой, полной неудачи:

• http://tomcat.apache.org/tomcat-6.0-doc/index.html

Также FreeBSD Handbook является отличным примером документации и подхода OpenBSD. Они выбрасывают вещи, которые не документированы должным образом.

РЕДАКТИРОВАТЬ: этот список ни в коем случае не является полным, это просто основные вещи, которые сразу пришли мне в голову. Также документация должна быть хорошо читаемой, а не просто что-то, что читается, как кто-то вырвал .

Короче говоря, я ожидаю, что документация, которую я указываю и контракт для.

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

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

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

@Spoike (пока не могу комментировать ответы ..)

ИТ-разработчики (роль зависит от типа и размера фирмы) должны работать последовательно для достижения следующих целей:

• Минимальные требования к установке / обновлению - иными словами, ИТ не могут быть пассивными и ожидать, что разработчики «узнают», какая информация необходима во время установки / обновления. Я обнаружил, что в ИТ часто бывают значительные путаницы / разногласия относительно того, что составляет надлежащую документацию приложения. Dev понимает требования (мы надеемся), и ИТ-отдел должен собраться, чтобы найти то, что - как минимум - требуется.

• Процедура установки / оборота - в корпоративных настройках вы можете называть это Change Control или Governance, но по сути это стандартный цикл проверки, в котором ИТ-специалисты проводят первичную установку Dev PRIOR, чтобы получить краткую информацию о продукте и его потребностях.

Установка приложения мало чем отличается от дебюта в театральной постановке. Перед тем, как занавес поднимется, директор (ведущий разработчик) неоднократно встречается со съемочной группой (ИТ-разработчиками), чтобы убедиться, что все «просто так» для премьеры (публичная установка).

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