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

Тож мені просто цікаво ... Які обов'язкові технічні та нетехнічні документи, які я можу дати своєму клієнту, крім документації про код і архітектуру?

(Також було б якось здорово вдарити клієнта про різні статистичні дані та дані про проект, щоб він насправді знав обсяг роботи та наскільки класний продукт насправді.)

Я думаю, що список повинен включати:

• Нетехнічні вимоги (був такий документ, правда?)
• Технічні вимоги
• Документ "рішення" (якщо він був один), який пояснює, чому одні рішення приймалися над іншими. Це може бути вже в інших вимогах або архітектурному документі, але ми зазвичай робимо це окремо для великих рішень.
• Код та інші ресурси (файли зображень, CSS тощо)
• Модель бази даних (як діаграма, документ, що завгодно)
• DDL для створення бази даних.
• DML для занесення бази даних.
• Документ, що пояснює налаштування програми та усунення основних проблем.
• Перелік важливих імен користувачів та їх паролів (для облікових записів адміністратора), а також інструкції щодо зміни пароля. В ідеалі, коли вони вперше налаштували веб-сайт, їм слід запропонувати ввести новий адміністраторський пароль, але це більше стосується архітектури.
• Системні вимоги, а також для веб-додатків мінімальні вимоги до хостингу (чи потрібна програма MySQL або PostgreSQL? Скільки оперативної пам’яті? Тощо).

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

На додаток до справді гарної відповіді FrustratedWithFormsDesigner, я хотів би сказати, що включає нетехнічні документи (як ми це зробили):

• дані аналізу: що сказав вам замовник, коли ви вперше говорили про вимоги?

• пропозиція, яку ви зробили:

  • документ про вимогу до товару
  • і документ про функціональну специфікацію

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

• специфікація, включаючи протоколи огляду, шаблони використання та тестові плани, тестові результати

• дизайн в UML та всі відповідні документи

• документація вихідного коду (доксиген або інше)

• керівництво та інструкції з монтажу

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

• деякі замовники хочуть також протоколів зустрічей, які потім є розширенням до згаданого вище "документа про рішення"

Сподіваюсь, що це те, що ви шукали.

Дотримуйтесь будь-якої документації, яка застосовується для вашого проекту, з наступного. Можливо, деякі з них уже є.

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

• Детальніше про 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, які можуть допомогти підготувати важливу статистику ваших даних.

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

• Нарешті закінчіть зі статистикою, такою як загальна кількість рядків коду, загальна кількість днів, проведених до проекту, загальна кількість перевірених вами проектів, перелік усіх використаних додатків та інша технічна та нетехнічна інформація.

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

• Деталі ліцензування проекту, якщо це можливо.
• Комерційні аспекти проекту, якщо це застосовується.

Будьте обережні

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

Чому клієнт хоче цю документацію (вище вихідного коду)? Що з цим буде зроблено? Для кого це?

Відповіді на ці запитання допоможуть звузити сферу того, що потрібно надати.

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

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

Я, мабуть, розділив це на кілька категорій документів:

Посібники:

• Посібник з установки, як це зробити на сервері.
• Посібник адміністратора, як налаштувати та запустити програму для досягнення оптимальної продуктивності. Тут також слід охоплювати безпеку, щоб було відомо, які паролі має ця програма та використовується для її запуску.

Підтримка:

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

Інтеграційні бали:

• Чи є сторонні точки інтеграції для цієї програми, які змушують її покладатися на інших постачальників, ніж ваш код?