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

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

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

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

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

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

Вот тут что то было.
В принципе есчё в гостах за 2008 год что то было, только нужно искать в них...

Спасибо .

какую же документацию в конце концов Вы предоставили?

В конце концов, когда я сказал начальнику, что на разработку документации надо столько-то времени, он сказал, что есть более приоритетные задачи .
Так что, предоставление отсрочилось на неопределенное время.

Так и живем...

А если так подумать, какую б документацию на выполненный проект Вы предоставили?
Естественно коды программ на HDL и С для микропроцессора - будут всегда. Кроме них, что?
Чтобы потом так например годика через N открыли, прочитали и все вспомнили что, зачем и как

PS Я спрашиваю из-за того что хотел бы узнать мысли людей по этому поводу.

Мы закладывали прошивку конфигурационных ПЗУ.
Как на обычные ПЗУ-шки. Файл на машинном носителе, лист ИПХ (это для магнитного архива, типа формуляра) и лист утверждения.
Исходники проекта - на совести разработчика и начальника.
Ну а в принципе, чем ПЛИС формально отличается от того же контроллера?
Так же и закладывать, как обычное встраиваемое/прошиваемое ПО.
Исходные тексты, бинарник, листы утверждения, спецификация.


Вы бы ещё сказали, пришёл человек с улицы, прочитал, всё понял и пошёл работать!
Я вот смотрю сейчас на свои проекты 2-летней давности и не могу понять - как я мог ТАКОЕ написать!

но все таки отличия есть... И Вы это прекрасно знаете



Как я понимаю именно для этого же и делается документация
Или нет, так для сбора макулатуры и подставок под чашки чая/кофе в виде CD/DVD

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

Я писал как-то методику тестирования ПЛИС. Там система связи была и проверялось смещение по доплеру и гауссовский шум.
Так вот было полное описание того, как все это тестируется вплоть до структурного описания каждого блока со схемой. В отдельной папке лежали несколько прошивок и готовые проекты под chipscop для разных прошивок, там же была приведена таблица с примерными результатами и графики. Был полностью описан порядок действия человека, который хочет проверить работоспособность системы связи начиная о того как прошить плисину и какие значения ввести в XMD чтоб задать некое соотношение сигнало/шум. Всю эту последовательность действий проводил студент третьего курса, который вообще в этом не разбирался, ну и данной методикой испытания вроде как уже два года пользуются

Это другой вид документации, не проектно-конструкторская, а эксплуатационно-сервисная.

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

Наверно сопроводительная документация, точно не скажу

В ЕСПД есть документ «Описание программы».
Напомню ГОСТ.
Описание программы должно содержать следующие разделы:

• общие сведения;
• функциональное назначение;
• описание логической структуры;
• используемые технические средства;
• вызов и загрузка;
• входные и выходные данные.

В зависимости от особенностей программы допускается вводить дополнительные разделы или объединять отдельные разделы.
Допускается содержание разделов иллюстрировать пояснительными примерами, таблицами, схемами, графиками.
В приложение к описанию программы допускается включать различные материалы, которые нецелесообразно включать в разделы описания.
ИМХО, все что вы описали можно уложить в Описание.

Звучит очень категорично. По моему скромному мнению, это только лишь ваш личный опыт. Практика показывает, в хорошо документированном коде, не являющимся «чужим говном», разобраться не так уж и сложно. Другой вопрос, что среднестатистический (читай средненький) программист не склонен подробно даже комментировать собственный код, так как уверен, что пишет его только для себя. Не говоря уже об Описании или других сопроводительных документах. И тут многое зависит от работодателя. Если работодатель платит за то, «чтоб работало» — подход с постоянной ориентацией на автора (не вижу в этом ничего криминального). Если платит за разработку изделия, то платит в числе прочего за КД, как за основной продукт труда.


Полагаю так:
1. Служебные записки, извещения, прочие внутренние стандарты документооборота.
2. ЕСКД, ЕСПД.

Отнюдь. Откройте стандарт своего предприятия, и посмотрите на перечень разрабатываемой документации.
В том или ином составе. Это ведь денежку стоит.
Так что инструкция по прожигу ПЗУ. И ничего более.

Что именно стоит денежку?
Ну это зависит не только от разработчика в вашем лице, а от договоренности сторон. У вас такие заказчики или стандарты на предприятии, у кого-то другие.

З. Ы. То, что инструкция по прожигу с прошивкой в придачу стоит в n раз дешевле полноценной разработки, это ясно.

Я бы еще один вопрос поставил:
Какую документацию на выполненный проект Вы бы потребовали с исполнителя ?

можно и так...

+1. Кто платит - тот и заказывает музыку. Будь то начальник или непосредственно заказчик.
Вопросы возникают только тогда, когда клиент сам заранее не знает, что хочет получить, и поэтому начинает пытаться менять предпочтения в пределах заранее оговоренного бюджета. Вариантов типов проектов море, есть одноразовые, есть которые должны жить и развиваться десятилетия при разных разработчиках. Долгую жизнь проекта нужно закладывать с самого начала, инвестируя в это соответствующие усилия.

Вы правильно говорите. Здесь как раз я хотел бы рассмотреть эти вопросы, чтобы в дальнейшем избавится от проблем

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

Oldring, с заказчиком — понятно. Как быть с частным случаем — работодателем?
Если: оформлен по классическому ТД, есть должностная инструкция. Существуют требования, обязанности и ответственность. Ну и оклад, разумеется. Дополнительных денег будут стоить «человекочасы» оформления соответствующей КД. И всё.

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

Извиняюсь за некоторый оффтопик, но дабы не создавать новую тему, задам вопрос здесь.

Вот, предположим, идет некоторая работа (ОКР, НИР, какой-либо коммерческий заказ - не суть важно что именно). Я делаю, например, Матлабовские модели (а я их делаю), разрабатываю прошивку ПЛИС (и это тоже делаю), возможно, пишу какой-то очень специфический софт в помощь себе любимому.

Заказчику мы отдаем скомпиленные прошивки, инструкции по настройке девайса, инструкцию по программированию ромов в девайсе, ну и прочие документы. Исходников еще ни разу не передавали.

А вопрос мой заключается в следующем.
Предположим, начальство говорит что (ну или заказчик) необходимо передать сорцы. Не будем обращать внимания на то, что есть либо нет пункта о передаче исходников в ведомости исполнения на каком-либо из этапов. Меня волнует следующий момент - если я в своих сорцах (матлабовских/etc моделях, плисовских сорцах, том же вспомогательном самописном софте) применил какие-то авторские приемы (не патент). Да и сами программы/модели по своей сути могут быть достаточно уникальными (в плане организации, например). Так вот - это же, по идее мои, авторские находки (особенно вспомогательный софт, который делается исключительно для личного удобства, но впоследствии может быть потребован заказчиком). Неужели я буду вынужден вот так просто отдать все это, не получив от этого процент? Звучит, наверное, корыстно, но - почему бы и нет, собственно говоря...

spectr, выскажу свое мнение.
Полагаю, в вашем конкретном случае все регулируется договором с заказчиком. Там должно быть всё прописано.
Существуют еще патенты, соавторство с ген. диром и прочие «договорные отношения».

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

Все должно быть описано в договоре по пунктам. Допустим фирма А разрабатывает часть какой-либо системы для фирмы Б. Так вот очень часто бывает прописано, что все исходники и модели для повторного использования принадлежат как А так и Б. Возможна ситуация, что все принадлежит только фирме Б и даже, если именно Вы все реализовали, то не имеете право на повторное использование своих же описаний или модели . А о своих процентах можете забыть - это фантастика. Вы их можете получить только по патенту, только вот проблема в том, что я лично никогда не видел ОКР или НИР, где специальным пунктом не была бы обозначена позиция, что все патенты, полученные по результатам данных работ, заказчику (и, возможно, Вам).

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

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

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



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

Читайте законы.
Авторское право за Вами навечно, этого никто не отнимет. Да и зачем, ведь чисто в материальном плане оно вам ничего не даёт.
Вот если оформить свидетельство на изобретение, тогда возможны варианты (и то зависит от конторы и начальства)
А всё, что вы произвели за зарплату, принадлежит тому, кто эту зарплату выдаёт.
То есть авторское право за вами, а право собственности на интеллектуальный продукт, произведённый вами - у вашего работодателя.
Если иное не оговорено в трудовом договоре.
Вот если вы работаете не за зарплату, тогда другое дело.
Опять же, зависит от договора.

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