Каков критерий нормальной документации?
Серьезнейший вопрос. Думаю, что одного-единственного критерия нет, так же, как нет критерия "хорошей книги".
Я, пожалуй, отмечу шесть:
1. Освещение вопросов не с точки зрения производителя, а с точки зрения пользователя. То, есть, основное внимание не на то, как это устроено и как это действует, хотя такие разделы и должны быть, а на то, как с этим работать, как этим пользоваться.
2. Структуризация, выделение доминирующих позиций, ключевых для использования продукции.
3. Понятность и подробность, простой язык с общепринятой терминологией и разъяснением редких или своих терминов.
4. Определение границ и особенностей использования.
5. Отсутствие фактических ощибок.
6. Соответствие ГОСТу с учетом того, что ГОСТ не догма.
Еще есть такое зыбкое и расплывчатое понятие и даже не понятие, а скорее, ощущение позиционирования себя техническим писателем - есть позиция: я такой умный, а вы вот неизвестно кто, а есть - я умный и вы умные, только пока знаете немножко меньше меня, но я с вами своим знанием делюсь на понятном языке.
И еще один, критерий, но совсем трудно объяснимый - текст должен "журчать". Как ручеёк. Чтобы читатель не продирался сквозь него, а впитывал. А для этого над ним надо много работать. Написать хороший научный и технический текст, на мой взгляд, сложнее, чем художественную книгу. Недаром так редки хорошие популяризаторы науки, которые могли простым языком описывать сложные явления. Профессия технического писателя - это отдельная очень сложная профессия.
Понятно....
Ответ не о чем.
Хотя бы потому, что очевиден следующий вопрос - каков должен быть уровень читателя данной книги? Как пример - должен ли он знать интегральное и дифференциальное исчисление? Физику автоматизируемых процессов? Дискретную математику? Теорию автоматического управления?
Или только БУКВАРЬ?
Вообщем то все Ваши суждения в этом вопросе ошибочны. Во что превратится высшая школа, если ученики будут делать такие заявления, которые Вы тут изложили. На требование "по журчать" преподаватель на первый раз скажет, не успеваешь за группой найми репетитора, а во второй раз похадатайствует об отчислении.
Почему же в нашей сфере программирования должно быть по другому, если не дано и если не схватываете, то Вам надо остановиться, а не требовать чтоб на Вас другие тратили время да еще и безвозмездно
Для Михаила Ивановича:
Все эти разговоры про "понятные" книги - это детский лепет.
Вы попробуйте почитать про радиолокацию, например.
Даже на начальном уровне Вы столкнетесь с таким количеством "непонятных" терминов, понятий и выражений, что, скорее всего, закроете книгу и пойдёте изучать высшую математику, физику, информатику и другие нужные для понимания данного материала дисциплины.
Почему же Вы решили, что составление технического задания, выбор ПЛК, алгоритмирование, программирование, отладка программ - это то, что может усвоить человек, который не имеет соответствующих сопутствующих знаний?
Спасибо КоДеСис и Овен, что они и так максимально облегчили процесс изучения программирования и работы с ПЛК до уровня простого инженера.
Но, как ни крути - данная литература - это не развлекательное чтение и не роман, который "журчит, как ручеёк", а литература ТЕХНИЧЕСКАЯ.
Цель которой - дать необходимые сведения в необходимом объёме без цветистых описаний и красочных сравнений, как это бывает в художественной литературе. Для того, чтобы без проблем читать эту литературу и получать знания при помощи подобной литературы, нужно быть технически грамотным человеком, который УМЕЕТ ЕЙ ПОЛЬЗОВАТЬСЯ.
Поэтому, тому, кто требует "журчания" и других украшений текстов - прямая дорога в литераторы, но, никак не в техническую область, ИМХО.
Извините, если чем-то обидел.
Последний раз редактировалось kolyan; 16.12.2012 в 13:34.
Нет не должен.
Технологию безусловно, физику нет.
Желательно но не обязательно.
Пустопорожние переливания из отечественной академической литературы? Ни вкоем случае!
Школьный учебник информатики и букварь по азам электротехники, - вот все что нужно знать. Просто инструкции надо читать в полном объеме, документация овена ничем не хуже сименса или шнайдера, а если сравнивать только русскоязычную документацию - то овен вообще вне конкуренции.
Последний раз редактировалось SBER; 16.12.2012 в 17:18.