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

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

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

Проект был разработан с использованием PHP и MySQL. Функции плохо прокомментированы, поэтому я не могу получить хорошие результаты при запуске с doxygen.

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

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

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

1. Варианты использования, с которыми встречается продукт. Это может быть трудно, учитывая возраст продукта, но получение информации о том, для чего предназначен этот продукт, дает жизненно важный контекст нетехническим читателям и тестировщикам. Кто являются конкурентами на рынке (если есть)? Что-нибудь исключено из сферы действия продукта?
2. Любые четкие нефункциональные требования . Например, был ли продукт написан для обработки определенного объема? Сколько лет могут быть данные? Где используется кэширование? Как проходят аутентификацию пользователей? Как работает контроль доступа?
3. Контекст схема , показывающая взаимодействие с другими системами, такими как базы данных, источники аутентификации, резервное копирование, мониторинг и так далее.
4. (Если известно) Риски и способы их снижения, а также реестр решений . Это, вероятно, сложно оглянуться назад, но часто есть важные решения, которые влияют на дизайн. Захватите все, что вы знаете.
5. Общие шаблоны проектирования или рекомендации по проектированию . Например, есть ли стандартный способ доступа к базе данных? Существует ли стандарт кодирования или именования?
6. Критические пути кода , обычно с использованием блок-схем или UML-операций или диаграмм последовательности. В проекте может не быть ни одного, но обычно это те, о которых бизнес-пользователи сформулировали.

Даже если вся эта информация недоступна, начните прямо сейчас . Разработчики, которые придут за вами, будут вам благодарны.

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

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

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

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

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

Перво-наперво, кто ваша целевая аудитория? Будущие разработчики или другие деловые люди? Имея в виду ответ на этот вопрос:

Как уже говорили другие, первое, что вам нужно, - это описание высокого уровня. Объясните, что система пытается сделать в более широком смысле. Объясните, на чем он работает, как он вписывается в сеть и общается с любой другой системой. Затем я просматривал каждый экран, снимал его с экрана и давал быстрое объяснение того, что делает экран, и как он взаимодействует с любыми другими частями системы. Если это для разработчиков, держите его в диалоге, как будто вы объясняете им приложение в первый раз. В конце концов, в этом суть документа (я полагаю).

Любая сложная обработка или логика я бы использовал диаграмму состояний, диаграмму потока данных или диаграмму последовательности. Определенно сделайте диаграмму сущности, затем проект схемы БД (две разные вещи!). Может быть, базовая диаграмма классов, но не усложняйте ее, обратите внимание только на основные вещи, которые интересны, разработчики могут понять это, взглянув на код.

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

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

Вопрос в том, хотите ли вы документировать это как сейчас или как должно быть?

Что я прочитал из вашего вопроса, так это то, что вы думаете о документации API, а не о пользовательской документации, и код, возможно, не так хорошо поддерживается и загадочен.

Боюсь, что если вы сейчас запишете документы, вы в конечном итоге отбросите большую часть своей работы после реорганизации кода.

Я бы выбрал следующий подход:

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

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