требования к документации Опции

[Maverick]

Задача такая есть заказчик (в данном случае допустим я) и есть исполнитель (в лице другого предприятия). Исполнителю было поручено разработать цифровой блок на VHDL (исходные коды предоставил), но для более быстрого понимания работы написанного кода хотелось бы:

P.S. Это как я попытался сформулировать:

Требования к написанию программ и документации для ПЛИС

• Файл/документ, содержащий описание всех констант, переменных, сигналов.
• TEST BENCH файл/документ с описанием для возможности моделирования работы.
• Описание работы функциональной модели (схема, конечный автомат состояний (диаграмма состояний конечного автомата), и временная диаграмма работы (скриншоты с ModelSim).
• В исходном коде программы должны присутствовать комментарии, облегчающие понимание программы.
• Подробное описание всех входных и выходных сигналов с предъявляемыми к ним требованиями (например потенциальная или импульсная команда(ее длительность)).
• По возможности большую программу/схему разбивать на подпрограммы/подсхемы.
• На начальном уровне соединение всех функциональных блоков производить в Schematic Editor (например, Синхрогенератор <=> Модуль связи УПСОС-ПК) (может заменить функциональную/структурную схему).
• При использовании ядер из CoreGenerator описать процесс создания.
• При написании исходного кода программы максимально использовать механизм настраиваемых параметров Generic (например, для разрядности данных, адресов и т. д.).

Но мое начальство говорит, что лучше руководствоваться ГОСТами. Соответственно вопрос есть ли какой то ГОСТ на оформление документации (для программ для ПЛИС).

P.S. Прошу прощения, что может не в тему. Просто здесь чаще бывают люди которые с этим непосредственно связаны

[Guest_@Ark_*]

для того чтобы написать качественное ТЗ необходимо иметь нормальные исходные данные...

Ну, как формируется ТЗ мне не нужно рассказывать.

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

В приведенном мною примере, установку эксплуатировали совсем не рядовые операторы, а большие спецы в своей области. И делали это с полным пониманием процессов и досканальным знанием аппаратуры. Но их знания от том, как это было реализовано 30 лет назад, а также документация на установку (которая имелась в полном объеме),
интересовали нас в последнюю очередь. При написании ТЗ формулировались требования как это должно быть с их точки зрения, без относительно к реализации 30-летней давности. Как я уже говорил, по части вопросов, единого мнения у них не было, а по некоторым - не было вообще ни какого. Потому как для эксплуатации эти моменты были не важны, а для разработки - очень существенны. Только искать истину, предложенным Вами способом, мы не стали. Просто собрали опытный образец, в процессе эксплуатации которого получили точные ответы на все интересующие вопросы, а не чьи-то мнения по этому поводу. Так оно надежнее.
Конечно, понимаю, что ваша область имеет специфику. и не все методы там применимы. Но речь не об этом, а о ценности и полезности документации для повторной разработки. Например, ТЗ, по которому разрабатывалась установка 30-лет назад, у нас не было - а очень бы помогло. Или, например, подробное описание алгоритма управления с его обоснованием очень бы пригодилось, а не исходный текст программы на давно забытом языке, хотя и с комментариями. А подробная электрическая схема потребовалась только для описания распиновки внешних разъемов.