Вы должны разделить это на две части:
- Что ты хочешь сказать?
- Какой лучший способ сказать это?
Какой бы формализм вы ни использовали для ответа на вторую часть, вы должны быть уверены, что он не является двусмысленным.
Преимущество UML в том, что язык уже определил много семантики, поэтому вам не нужно включать определение того, что означают эти поля, линии и стрелки в диаграмме сотрудничества.
Но самое главное, документирование чего-либо означает создание пути для других, чтобы понять предмет, который вы документируете. Очень точное описание, которое не дает подсказки о том, как его читать, так же хорошо, как и ничего. Поэтому используйте UML, конечные автоматы, диаграммы ER, простой английский, что хотите, но обязательно указывайте логический путь, по которому ваши «читатели» могут следовать, чтобы понять, что происходит.
У меня был друг, который был поклонником «точности любой ценой», и он попросил бы нас пройтись по всем деталям, прежде чем появится какое-то значение.
Однажды я попросил его провести этот эксперимент: во время его следующей поездки в неизвестный город он должен был иметь при себе самую точную карту, какую только мог получить. Намного лучше, он должен был бы иметь карту города 1: 1 с каждой деталью, точно сообщенной в масштабе. Таким образом он не мог потеряться!
Он отказался, но мне бы очень хотелось увидеть, как он пытается использовать эту карту. Просто даже сложить! :)