Документация на "прошивку" ПЛИС - что, как? Опции

[Koluchiy]

Здравствуйте.

Пристал начальник на предмет оформления документации на находящуюся в разработке прошивку для ПЛИС Xilinx.
В качестве образца дается нечто странное.

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

Есть ли на это какие-то ГОСТы, IEEEEEE, или прочие стандарты?

В проекте есть 1 штука ПЛИС Xilinx Spartan3, в ней система с Microblaze (+ программа на С) и кучка логики, написанной на Verilog.

Всем заранее спасибо .

[Guest_@Ark_*]

Когда-то имели с коллегами довольно жаркие дебаты на тему оформления документации, и пришли, примерно, к следующим выводам:
- документация документации - рознь, на один и тот же проект может существовать несколько различных видов (пакетов) документации, практически, не взаимосвязанных друг с другом.
- требования к конкретным пакетам документации могут (вернее, должны быть) совершенно различными, и определяются тем, кому они предназначены и для каких целей служат.
- можно выделить три основных пакета: документация для производства, документация для конечного пользователя, документация для поддержки проекта.
С документацией для производства - все более или менее ясно. Она должна быть оформлена по соответствующим стандартам, и содержать исчепывающую информацию по изготовлению и тестированию конечного продукта, без участия авторов. В случае встроенного ПО - это файлы и инструкции по их прошивке, описание тестовых процедур, прилагаемых тестовых программ и так далее. В общем, все необходимое для производства, и ничего лишнего.
Документация для конечного пользователя - это инструкции по эксплуатации, настройке, установке (если нужно), пользовательское описание, материалы рекламного характера. Здесь многое зависит от назначения продукта, и кто является конечным пользователем. Понятно, что описание для бытового прибора, предназначенное для обывателя, и описание какого-то специализированного модуля, предназначенного для разработчиков систем, могут радикально различаться и по форме, и по содержанию, и по стилю изложения. Нужно ли, при этом, загонять себя в рамки каких-то стандартов - к единому мнению не пришли. Я остался на позиции, что это не должно быть обязательным. Например, описание для бытового прибора, (которое, попутно, должно выполнять еще и рекламные функции), выполненное строго по ГОСТу - выглядит несуразно, с моей точки зрения, и совсем не способствует достижению конечной цели - привлечению потенциальных покупателей.
Документация для сопровождения проекта - это внутренняя кухня разработчика (исходные тексты программ, используемые библиотеки и их описания, и пр.). Цель ее создания - возможность, через какое-то время, вернуться к модернизации продукта или исправлению обнаруженных ошибок (автору или другому специалисту). Это сугубо внутренняя документация, которая должна оставаться у разработчика (и/или работодателя), и не должна передаваться заказчику. По крайней мере, бесплатно. Этот вопрос - возможность такой передачи и ее стоимость - должен быть оговорен заранее. По моему мнению, передача этой документации заказчику должна сопровождаться отказом от дальнейшей поддержки продукта разработчиком. Т.е. либо эта информация остается у разработчика, и он осуществляет сопровождение и исправление найденных ошибок. Либо все передается заказчику, и тогда уже - ни каких претензий в последствии. При необходимости, он будет решать проблемы самостоятельно или нанимать соответствующих специалистов (может быть авторов или других). Это, на мой взгляд, очень важный момент. Передавая эту документацию, вы открываете возможность модернизации продукта самим заказчиком. Что, как и кем там будет модернизировано - автор уже не контролирует ситуацию. Оставлять за собой какие-либо обязательства, в этом случае, нельзя. Я полагаю, заказчика надо ставить перед таким выбором: получаете полную документацию по разработке - лишаетесь авторского сопровождения. Либо-либо.