Во-первых,
Если вы делаете документацию, у нее должна быть «четкая» причина / цель.
И эта цель - определить природу вашей документации.
Во-вторых:
Не думайте о документации просто в «письменной форме» или в словесном документе.
Это может быть в любой форме. Даже это может быть "видео", в котором какой-то парень
объясните свои основные архитектурные решения и почему они выбирают
это [мотивация]
Итак, предположим, что вы хотите, чтобы новые члены команды "легко улавливали" то, что вы делаете, как вы делаете и почему вы делаете это. [Будьте осторожны, все зависит от вашей проблемной природы]
- Диаграмма вариантов использования UML может дать общую картину вашего функционала
требования. В нем просто говорится, кто будет использовать вашу систему, и что они могут
делать с вашей системой.
- Короткие заметки, в которых изложены важные нефункциональные требования
- Короткие записки, в которых указано ваше основное архитектурное решение и почему вы его принимаете
- Может быть, диаграммы компонентов, которые показывают ваши важные компоненты и их интерфейсы
- Если тапология приложения важна, тогда может быть диаграмма развертывания UML, которая показывает, как ваша система будет физически развернута.
Но, в конце концов, вы не можете документировать все и не должны. Вы можете автоматически генерировать диаграмму классов всей системы UML с помощью инструмента UML, но как это может помочь новичку.
- Но вы можете поместить диаграммы классов для классов, которые делают важные и хитрые
части и нарисуйте диаграммы последовательности для тех хитрых частей, которые показывают, как
они сотрудничают с другими классами, в то время как они выполняют важные и
хитрые обязанности.
Ключом к документированию является попадание в свою «аудиторию» [кто
прочту ваш документ] и спросите себя
- Если бы я был этим документом, то я буду читать этот документ? [Если нет, почему вы делаете документ]
- Если я прочитаю этот документ, поможет ли он мне как-нибудь? [это эффективно]
Наконец, мы не живем в «идеальном слове» ... Иногда вы можете обнаружить, что делаете документ без реальной аудитории и без реальной причины только из-за некоторой «политики», и вы должны зарабатывать деньги
Ну, в этой ситуации UML поможет. Нарисуйте скучно со множеством подробных [генерируемых автоматически] диаграмм, которые никто не читает и не понимает, но говорит: «О, у вас есть обширная документация». В нашей индустрии программного обеспечения UML переоценен, и многие парни «покупают» даже плохой документ, если в нем есть UML-диаграммы.
Вот и все, ребята ...