Як задокументувати вже розроблений проект?

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

У проекті немає інших деталей, окрім багатьох сторінок сценаріїв з функціями, написаними та модифікованими розробниками, які працювали над цим проектом протягом останніх 2 років. Все, що у мене є, це схема бази даних та файли проектів. Мені хотілося б знати, чи є якийсь спосіб організувати цей проект і документувати його, щоб він міг бути корисним розробникам, які працюватимуть над цим проектом у майбутньому.

Проект розроблявся за допомогою PHP та MySQL. Функції погано коментуються, тому я не можу отримати хороших результатів, коли запускаю його з доксигеном.

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

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

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

1. У випадках використання продукт відповідає. Це може бути складно з огляду на вік продукту, але відображення того, що продукт має на меті, дає життєво важливий контекст для нетехнічних читачів та тестерів. Хто такі конкуренти на ринку (якщо такі є)? Чи є щось, що виключається із сфери застосування товару?
2. Будь-які чіткі нефункціональні вимоги . Наприклад, чи був написаний продукт для обробки певного обсягу? Скільки років можуть бути дані? Де використовується кешування? Як аутентифікуються користувачі? Як працює контроль доступу?
3. Контекст схема , що показує взаємодію з іншими системами, такими як бази даних, джерела аутентифікації, резервне копіювання, моніторинг і так далі.
4. (Якщо відомо) Ризики та способи їх зменшення разом з реєстром рішень . Зрештою, це, мабуть, складно, але часто існують критичні рішення, які впливають на дизайн. Захопіть будь-яке, що вам відомо.
5. Загальні шаблони дизайну або інструкції щодо дизайну . Наприклад, чи існує стандартний спосіб доступу до бази даних? Чи є стандарт кодування чи іменування?
6. Критичні кодові шляхи , як правило, використовуючи діаграми потоків або активність UML або діаграми послідовностей. У проекті їх може бути не було, але це, як правило, ті, хто бізнес-користувачів сформулював.

Навіть якщо вся ця інформація недоступна, починайте зараз . Розробники, які прийдуть за вами, будуть вам вдячні.

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

Це також здається, що вам потрібно внести культурні зміни, щоб включити документацію . Почніть з невеликого, але в ідеалі проект не слід «робити», поки він не має хоча б мінімального рівня документації. Це, мабуть, найважчий крок, тому що вище - це речі, якими ви можете керувати. Це те, що повинні купувати інші. Однак це також може бути найбільш корисним, особливо якщо наступний проект, який ви робите, має хорошу документацію.

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

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

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

Перш за все, хто ваша цільова аудиторія? Майбутні розробники чи інші ділові люди? Маючи на увазі відповідь на це питання:

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

При будь-якій складній обробці чи логіці я використовую діаграму стану, діаграму потоку даних або послідовну діаграму. Однозначно зробіть діаграму об'єкта, а потім розробити схему БД (дві різні речі!). Можливо, основна схема класу, але зберігайте її просто, зазначайте лише основні речі, які цікавлять, розробники можуть зрозуміти це, переглянувши код.

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

Попередні пропозиції є хорошими, але я також розглядаю, чи ваша спільнота користувачів створила будь-яку спеціальну документацію. У вашому запитанні не було вказано, чи будь-яка версія вашого продукту (що існує два роки) коли-небудь була випущена користувачами. Якщо він використовувався, а офіційної документації немає, то або жодна документація не потрібна, або є десь "неофіційна" документація, яка може бути рудиментарною, але також, ймовірно, сприймається користувачем як важлива. Спробуйте здійснити пошук в Інтернеті артефактів, які можуть представляти критичні API, пошукові форуми, задайте користувачі енергії та пошукайте питання та відповіді на сайтах. По можливості спробуйте написати документацію, яка відповідає технічній чи діловій потребі.

Питання полягає в тому, чи хочете ви документувати його таким, яким він є зараз, або як має бути?

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

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

Я б застосував такий підхід:

• зробити документацію максимально непотрібною, дотримуючись загальних найкращих практик. Виберіть хороші назви класів, назви методів, назви змінних, які ви можете зрозуміти інтуїтивно
• розбити величезні класи монстрів та / або функції, де це має сенс
• використовувати коментарі PHPdoc - ви можете використовувати інструменти для створення документації API
• написати тести для нього: Тести допоможуть вам зрозуміти або визначити, що повинен робити код.

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