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

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

(Также было бы неплохо поразить клиента различными статистическими данными и данными о проекте, чтобы он на самом деле знал объем работы и насколько крутой продукт на самом деле.)

Я думаю, что список должен включать в себя:

• Нетехнические требования (был такой документ, верно?)
• Технические требования
• Документ «решений» (если таковой был), объясняющий, почему некоторые решения были приняты над другими. Это может быть уже в другом документе с требованиями или архитектурой, но мы обычно делаем это отдельно для больших решений.
• Код и другие ресурсы (файлы изображений, CSS и т. Д.)
• Модель базы данных (как диаграмма, документ, что угодно)
• DDL для создания базы данных.
• DML для заполнения базы данных.
• Документ, объясняющий настройку приложения и основные способы устранения неполадок.
• Список любых важных имен пользователей и их паролей (для учетных записей администратора), а также инструкции по смене пароля. В идеале, когда они настраивают веб-сайт в первый раз, им нужно будет ввести новый пароль администратора, но это скорее вопрос архитектуры.
• Системные требования, а также для веб-приложений, минимальные требования к хостингу (Нужно ли приложению MySQL или PostgreSQL? Сколько оперативной памяти? И т. Д.)

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

В дополнение к действительно хорошему ответу FrustratedWithFormsDesigner, я хотел бы сказать, что входит в нетехнические документы (как мы это сделали):

• данные анализа: что клиент сказал вам, когда вы впервые говорили о требованиях?

• предложение, которое вы сделали:

  • документ с требованиями к продукту
  • и документ функциональной спецификации

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

• спецификация, включающая протоколы проверки, варианты использования и планы испытаний, результаты испытаний

• дизайн в UML и все соответствующие документы

• документация исходного кода (doxygen или что-то еще)

• руководство и руководство по установке

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

• некоторые клиенты также хотят протоколы собраний, которые являются расширением упомянутого выше «документа о решениях»

Надеюсь, это то, что вы искали.

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

Техническая документация:

• Подробная информация о PHP и информация о том, как это полезно для проекта
• Подробная информация о серверной части и информация о том, как это полезно для проекта
• Информация о подключении к базе данных вместе с подходящими картинками, изображающими поток данных
• Информация о других языках программирования или приложениях, участвующих в проекте, таких как XML, HTML и т. Д.
• FAQ Файл справки

Подготовьте документы со скриншотами и выделите соответствующий код (при необходимости) для следующего:

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

• Введите неверные данные и покажите, что это невозможно сделать, так как вы провели проверку данных на переднем и заднем концах.
  /* This step is not applicable if you have not used any object for getting direct input from the user like Text Field as it is obvious that you cannot get invalid data through indirect input. */

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

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

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

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

  
  Нетехническая документация:

• Лицензионные детали проекта, если применимо.
• Коммерческие аспекты проекта, если применимо.

Будь осторожен

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

Почему клиенту нужна эта документация (помимо исходного кода)? Что будет с этим сделано? Кто это для?

Ответы на эти вопросы помогут сузить рамки того, что нужно доставить.

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

Не играйте в угадайку. Большая часть технической документации будет бесполезна для типичного (нетехнического) клиента.

Вероятно, я бы разбил это на несколько категорий документов:

Гиды:

• Руководство по установке, как это настроить на сервере.
• Руководство администратора о том, как настроить и запустить приложение для оптимальной производительности. Безопасность также будет чем-то, что можно охватить здесь, просто чтобы знать, какие пароли это приложение имеет и использует для запуска.

Служба поддержки:

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

Точки интеграции:

• Существуют ли сторонние точки интеграции для этого приложения, которые заставляют его полагаться на других поставщиков, а не на ваш код?