Документация vs Нормоконтроль

Сергей

САБЖ. Это просто Ад.
Как описать в документации по-русски что такое:
- .NET Framework
- delegate
- exception
- throw, try, catch
- managed/unmanaged (safe/unsafe)

Коллеги рассказывали, что кучу времени потратили, чтобы объяснить нормоконТРОЛЮ что такое "драйвер" (на ПК).
Пришла моя участь

Michael_K

Забить и писать нормальным языком.
Среда, делегировать, исключение и т.п.

Отстаивать свою позицию - делать, так уж хорошо, а не "пусть косо, зато по правилам".

Сергей

Буду пробовать конечно

Angel71

докладная записка о несоответствии занимаемой ими должности, в следствии недостаточной квалификации не вариант? :oops:

или с начальством еще не всё потеряно?

Сергей

Не вариант, конечно. Там все "укоренились" давно.

Виталий

Цитата:

- .NET Framework
- delegate
- exception
- throw, try, catch
- managed/unmanaged (safe/unsafe)

- Платформа .NET
- изначально делегат пришел из языка Оберон, где он является полем процедурного типа =)
- исключение
- сгенерировать/перехватить
- управляемый/неуправляемый, безопасный/небезопасный

Вобщем не вижу никаких проблем.

Добавлено спустя 6 минут 40 секунд:

Цитата:

Отстаивать свою позицию - делать, так уж хорошо.

Если у нормоконтроля такая же позиция, то не попрет.

Сергей

На неделе буду очередную правку документации производить, отпишусь на чем остановились

Michael_K

Это зависит от того, какие цели ставятся в проекте.
Сейчас реальных проектов мало, к сожалению. И все меньше становится...
Если цель - "отчитаться", или "изобразить деятельность", то вообще ничего не поможет...

Виталий

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

Но(!) если почитать то что обычно пишут в документации инженеры... вобщем это нельзя ни прочесть, ни понять.

Сергей, добавьте в документ глоссарий.

Angel71

дот нет это экосистема, но лучше про это умолчать
на вскидку вот из этого можно для начала чего состряпать

Цитата:

.NET Framework это среда выполнения для приложений нового поколения. Эта среда может быть установлена в любые версии Windows, начиная с Windows 98, и обеспечить виртуальную систему исполнения (Virtual Execution System) для приложений, созданных с помощью Visual Studio.NET.
Особенность приложений для .NET Framework заключается в том, что они, подобно приложениям Java, содержат не инструкции процессоров Intel, а инструкции виртуальной машины. В случае Java эти инструкции называются байт-код, в случае .NET Microsoft Intermediate Language (MSIL). Как показал опыт Java, вместо интерпретации кода виртуальной машины лучше транслировать его в инструкции реального процессора, такого как Intel Pentium, даже если это приходится делать непосредственно при исполнении приложения (Just In Time JIT). Поэтому .NET Framework вместо интерпретатора MSIL содержит его JIT-компилятор. Кроме того, существует возможность однократно выполнить прекомпиляцию (например, при установке программы) и пользоваться ее результатами в будущем.
Среда выполнения кода MSIL называется Common Language Runtime (CLR) и обеспечивает реализацию общих возможностей всех языков программирования .NET, что устраняет проблему взаимодействия компонентов, написанных на разных языках. Эта среда также обеспечивает возможность взаимодействия с компонентами COM+, что обеспечивает возможность доступа к прежним библиотекам компонентов.

http://www.williamspublishing.com/PDF/5-8459-0390-4/part.pdf
http://open-life.org/blog/mono/848.html
http://www.askit.ru/custom/asp_net/m1/01_net_framework_review.htm

Сергей

Michael_K писал(а):

Это зависит от того, какие цели ставятся в проекте.
Сейчас реальных проектов мало, к сожалению. И все меньше становится...
Если цель - "отчитаться", или "изобразить деятельность", то вообще ничего не поможет...

Проект реальный и устройства реальные. Документация нужна для заказчика, но ее выдаем по ГОСТу через нормоконтроль. А он, в свою очередь, к проекту никакого отношения не имеет, там сидит NPC бабушка, которой пытаешься сдать квест.

Michael_K

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

Вообще, сделать "формальную" сжатую доку "для бабушки" и внятную "пояснительную записку"
для работы.

D1mcon

Мне год назад пришлось долго и упорно обяснять эелементарное слово СИСТЕМА (заказ был сложный состоял из множества рабочих мест оператора и железа), в начале в тексте было указано название изделия, потом фраза:"Изделеие (код изделия) далее СИСТЕМА", вот эта фраза не вызвала ни каких нареканий, но на следующей странице снова было слово СИСТЕМА, и тут мне сказали, что ини не понимают что такое система :crazy:

, и такие замечания мне выдали к всем страницам где было написано слово СИСТЕМА.

И в чем прикол - ладно бы в 1 раз сдавал документацию, так ведь нет, и проверяльщики были теже :crazy:

.

Michael_K

а вы не употребляйте слов, которые ничего не значат.
пишите человеческим языком - не нужно этого бюрократического косноязычия.
вы в жизни часто слово "система" говорите?
расширять нужно словарный запас - книжки что-ли читать..

roboforum.ru

Документация vs Нормоконтроль

Кто сейчас на конференции