Как стать автором
Обновить

Комментарии 46

Ох уж эта документация… вечно больная тема для меня. Большое спасибо за ссылки, нужно все таки взяться и привести все в порядок наконец
Я себе это говорю уже пару лет, ага. :)
НЛО прилетело и опубликовало эту надпись здесь
Очень часто просто отмазка, нужная чтобы булевая функция «АуНасВашуМатьВообщеХотьКакаяТоДокументацияЕсть()» возвращала true.
Традиционная «бумажная» документация в миллионы раз чаще используется как Ваша булева функция.

Как правило, люди, использующие такие средства документирования, уже понимают, что без документации никуда.
Лично мне еще не попадалась совсем ужасная документация на doxygen, в отличие от бумажных носителей.
Лично мне довольно часто попадалась просто пустая документация на Doxygen. Ну или документация в духе: «Функция SetA(). Объяснение: устанавливает переменную А.». Хотя, справедливости рада, бестолковая бумажная документация встречалась не реже. Не в средствах дело, а в людях.
Благодарность не знает границ. Только подумал заняться поиском такой информации и вот она тут. Сам искал именно ISO/IEC 26514:2008

Есть даже описание, откуда брал не помню. Но интересен взгляд именно для пользователя.

ISO/IEC 26514:2008 «Разработка программного обеспечения и проектирование систем. Требования к проектировщикам и разработчикам документации для пользователя» охватывает этапы разработки, оформления и выпуска документации для пользователей. Стандарт устанавливает требования к структуре, содержанию информации и формату документации, включая печатные документы и документы, выводимые на экран, применяемые в рабочей среде пользователями систем, содержащих программное обеспечение. Стандарт рекомендует, чтобы разработка документации пользователя являлась частью разработки программного продукта и следовала тем же процессам, относящимся к жизненному циклу программного обеспечения. Документация пользователя остается важнейшим компонентом используемого программного продукта. ISO/IEC 26514:2008 может быть полезным для разработчиков следующих видов документации:

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

ISO/IEC 26514 – это первый стандарт из запланированной серии, касающейся документации для пользователей программного обеспечения. ISO/IEC 26514:2008 был разработан совместным техническим комитетом ISO/IEC JTC 1 «Информационные технологии» подкомитетом SC 7 «Разработка систем и программного обеспечения».

А так, я стараюсь создать шаблон и уже от него идти к конкретному сайту (Я их обычно в документации описываю.)
Нужно понимать, что не для каждой компании и продукта это подойдет. В мире «тяжелого энтерпрайза» это, скорее всего, просто не сработает (причем, не из за технических ограничений, а из за организационных, и бюрократии).

Сам лично я только за то, как это делают Сигналы, это очень круто. Надеюсь, со временем все более и более сложные системы можно будет строить, имея только простоту Getting Real.
НЛО прилетело и опубликовало эту надпись здесь
Ох уж это документирование. В свое время очень подробно занимался этим вопросом, поскольку приходилось работать в проекте, где средств на создание документации было выделено чуть ли не больше, чем на саму систему.

Нет, ну правда, круто было бы избавиться ото всех этих «ISO/IEC FDIS 18019:2004» (попробуйте это произнести, не то что прочитать док), и подобных и сделать все просто и на основе общих соглашений, ведь все, что нам нужно — это дать пользователю возможность выполнять свою работу.

Это же полная жесть — скоро начнут писать стандарты документов, описывающих документы, в которых написано про документы, описывающие рекомендации по документированию.
Стандарты и есть эти соглашения
Да, я понимаю, под соглашениями я подразумевал что-то более простое, чем строгий стандарт, в котором прописан каждый чих. В стандартизированную документацию зачастую закладывается слишком многое, из за чего она становится тяжеловесной, тяжелой к использованию, поддержке и слишком дорогой в содержании (Hello, YAGNI). Но при этом, раз приняли стандарт в какой-нибудь организации — обязуют ему следовать.
Немного оговорюсь — я не против стандартов как таковых, отнюдь. Я против их навязывания и чрезмерной строгости там, где это не нужно для дела. И _особенно_ это касается документации — ибо это не основной продукт, а сопутствующий.
Есть огромная разница между нашими стандартами и зарубежными.
У нас стандарт (ГОСТ) имеет ранг закона, он обязателен к исполнению. Любая гос. приемка может завернуть сделанную работу, если в документации рамочки не по госту. Это было сверхактуально в советское время, сейчас это актуально только для гос. заказов (оборонка, инфраструктура, лицензируемая деятельность и т.п.).
В Советском Союзе стандарты запрещалось переписывать, ксерокопировать, перепечатывать и так далее, требовалось обязательная покупка официальной книжечки с текстом стандарта (хотя конечно все на это клали). Стоили эти брошюрки копейки, и взять их можно было в любой библиотеке, но формально бесплатными стандарты СССР не были никогда. После распада Союза в какой-то момент возникла очень некрасивая ситуация, когда старый закон еще действовал, и распространение стандартов в электронной форме подмяли под себя фирмы, очень дружественные тогдашние руководителям Росстандарта. Эти фирмы взимали деньги в свой карман непонятно за что. Была серия громких скандалов, вроде бы после этого ситуацию урегулировали.
У «них» же стандарты — это рекомендации. От них можно отклоняться, если считаете целесообразным. Какие-то сложности могут возникнуть только при прохождении сертификации, но главенствует здравый смысл, поэтому если вы сможете убедительно доказать, что такое-то положение применить нельзя или вредно — вам это разрешат. И уж тем более, если какой-то пункт не проверяется при сертификации, или сертификация нужна не везде — вы также можете этот пункт не выполнять.
К чему всё это приводит — хорошо известно. Типичный пример — болты с какой-нибудь семигранной головкой, ключ к которым могут достать только сертифицированные сервис-центры, что приводит к искусственному ограничению конкуренции в сфере ремонтных услуг и навязывает сервис-центрам «сертификацию» у производителей.
Второе отличие состоит в том, что в СССР стандарты разрабатывали профильные НИИ, в современном же мире стандарты разрабатываются пулами производителей, которые конкурируют с группами других производителей. Вспомните войны Blue Ray против HD DVD, OOXML против ODF и т.п., расплачиваются за которые, разумеется, пользователи. Естественно, что коммерческие организации ничего бесплатно не делают, и за допуск к текстам стандартов также требуют денег.
О да, как же это бесило в институте! Сидишь, пишешь месяц какой-нибудь курсач или диплом, а твой одногруппник-раздолбай балду в это время гоняет. Потом идете сдавать. Тебя, не смотря на идеальный код, кучу идей и реально работающую программу посылают нафиг, ибо «рамочка не по ГОСТу», а коллегу, у которого работа состоит из идеально оформленной титулки, двух первых листов о том как «космические корабли бороздят просторы...» и 50 страниц кода ядра Линукса без правок вообще принимают на ура и ставят пятерку.
Тогда было очень обидно.
А теперь система окончательно вправила мозги?
Странно у вас как-то. Во всех известных мне вузах для курсовых и дипломных проектов было минимум 2 преподавателя:
1) нормоконтроль. его не интересует, что ты там написал и нарисовал. главное, чтобы всё соответствовало ГОСТу.
2) руководитель проекта. а вот его как-раз таки рамочки и не интересуют, он вдумчиво изучает суть работы. и именно он и ставит оценку за проект, при наличии подписи первого (нормоконтроль пройден).
Да, так и должно быть, конечно. Но в моем ВУЗе такого не было, к сожалению.
Вы не правы.
Далеко не все ГОСТ'ы обязательны к исполнению, в свою очередь есть зарубежные ст-ты обязятельные к применению. Можете посмотреть в сторону Директив ЕС.
Государственные службы не устанавливают большого количества обязательных стандартов за рубежом, т.к. существует система договорённостей между заказчиком и исполнителем. Когда заказчик предъявляет условия по выполнению какго-либо стандарта. Эта более гибкая система. Позволяет успевать за новейшими разработками. Если международный или другой региональный или национальный стандарт уже не актуален, можно создать свой. Который скорее всего станет основой для модернизации текущего стандарта в этой сфере.
В нашем случае гос. структуры хотят видеть всё в соответсвии с ГОСТ'ами. Это их прихоть. Обязательных для всех ГОСТ'ов не так уж и много.
> Когда заказчик предъявляет условия по выполнению какго-либо стандарта. Эта более гибкая система.

> В нашем случае гос. структуры хотят видеть всё в соответсвии с ГОСТ'ами. Это их прихоть.

По-моему, разница не так уж велика. В обоих случаях заказчик хочет/предъявляет условия по выполнению стандартов.
Платность и запрет на копирование стандартов в СССР объяснялись заботой об актульности стандарта для их потребителя. Типа чтобы каждый новый потребитель ГОСТа имел самый свежий текст стандарта. Разумно, но не очень понятно как они могли меняться — если менялись, то там же цифирька изменялась. Разве что косяки правились без смены цифры.
С развитием электронных коммуникаций такая форма поддержки актуальности потеряла смысл, а плату непонятно за что периодически таки пытаются вернуть…
Что-то мне подсказывает что цифирка не менялась(сейчас в названии госта никто ничего не меняет). Поэтому вполне правильно делали.
последние две цифры — это год принятия. «ГОСТ 19.102-77. Единая система программной документации. Стадии разработки.» — да-да, это именно 1977 год.
Меняются и циферки и названия, пример:

ГОСТ Р 34.10-94. Информационные технологии. Криптографическая защита информации. Процедуры выработки и проверки электронной цифровой подписи на базе асимметричного криптографического алгоритма

ГОСТ Р 34.10-2001 Информационная технология. Криптографическая защита информации. Процессы формирования и проверки электронной цифровой подписи
Не знал. Я думал в РФ и РБ одинаково. У нас ничего не меняют. Просто в тексте ст-та делается пометка что дополнен такого-то.
Второе отличие состоит в том, что в СССР стандарты разрабатывали профильные НИИ, в современном же мире стандарты разрабатываются пулами производителей, которые конкурируют с группами других производителей. Вспомните войны Blue Ray против HD DVD, OOXML против ODF и т.п., расплачиваются за которые, разумеется, пользователи. Естественно, что коммерческие организации ничего бесплатно не делают, и за допуск к текстам стандартов также требуют денег.

Зарубежные стандарты чаще всего разрабатываются не «пулами производителей», а профессиональными сообществами. Возьмем, например, ASTM (Американское общество по тестированию материалов), API (Американский интитут нефти) или хотя бы ISO (Международная организация по стандартизации), который упоминается в посте.

Это неправительственные некоммерческие организации, получающие средства для финансирования своей деятельности за счет продаж своих стандартов и изданий. Поэтому требование денег за доступ к стандартам — совершенно естественно.
Вы действительно думаете, что формат OOXML (ISO 29500) разработан ISO, а не единолично Microsoft? Примером «творения пула производителей» может служить ODF, он же ISO/IEC 26300, он же ГОСТ Р ИСО/МЭК 26300-2010
Коллега, не совсем так. В ранг закона возведены и обязательны к исполнению лишь часть ГОСТов, получивших даже отдельное название — «технические регламенты». Общее число ГОСТов порядка 22000 и лишь несколько сотен из них станут техническими регламентами.

ФЗ «О техническом регулировании» от 27.12.2002 N 184-ФЗ
технический регламент — документ, который принят международным договором Российской Федерации,… или нормативным правовым актом федерального органа исполнительной власти по техническому регулированию и устанавливает обязательные для применения и исполнения требования к объектам технического регулирования (продукции, в том числе ...;

стандарт (в том числе и ГОСТ) — документ, в котором в целях добровольного многократного использования устанавливаются характеристики продукции, правила осуществления и характеристики… Стандарт также может содержать правила и методы...;


chainik: У «них» же стандарты — это рекомендации...
Тоже не совсем так, российская реформа технического регулирования (стандартизации) пошла как раз по европейскому пути и технические регламенты — это прямой аналог Европейских директив.

Злоупотребление Росстандарта (Ростехрегулирования) при распространении российских и зарубежных НТД предмет отдельного разговора. Все дело в том, что российскому законодательству ГОСТы не являются объектами авторского права в отличии от зарубежных стандартов у которых имеются правообладатели. Если международным договором, в котором участвует Российская Федерация, установлены иные правила, чем те, которые содержатся в Законе Российской Федерации «Об авторском праве и смежных правах», то должны применяться правила международного договора.

Все ISO публикации защищены авторским правом. Поэтому и если не указано иное, никакая часть публикации ISO не может быть воспроизведена или использована в любой форме и любыми средствами, электронными или механическими, включая фотокопирование, микрофильмирование, сканирование, без письменного разрешения издателя.
Разработка документации времени отнимает колоссально.
Но я всегда замечаю кривые рамки.
Если не трудно, подкиньте оригинал комикса?

Спасибо.
Я так понимаю, каждый для себя делает файл шаблона по ГОСТу, формируя в нём все нужные стили. Может, кто-нибудь готов шаблон опубликовать, чтоб другим этот велосипед изобретать больше не приходилось?
Не было предела моему возмущению, когда я узнала, что международные стандарты не бесплатные. Это как правила дорожного движения сделать платными. Но в принципе, может и резонно: организации-то не государственные. Хотят – могут и деньги брать за свою работу. К счастью, многие стандарты можно скачать по-привычному, по-пиратски.

Автор, как я уже писала выше:

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

А скачать «по-привычному, по-пиратски» это так «по-нашему» в самом негативном смысле. Особенно если учесть, что использование нелигитимной (скачанной с инета, отсканированной и т.д.) версии зарубежного стандарта внутри организации это грубейшее нарушение авторских прав разработчика и грозит всеми видами ответственности, включая административную и уголовную. Распространение тоже, кстати.
Не люблю писать комментарии, но тут решила встрять. 1-ое расстраивает полное непонимание системы стандартизации как таковой.
1. Стандарт потому и платный, что он не правила дорожного движения, соблюдать которые положено всем. Это рекомендация – хочешь, пользуйся, а хочешь — нет, твое дело, как в случае применения внутри компании, так и в случае предъявления требований к поставщикам. Короче дело личное. Ну а если ты поставщик, то будешь плясать под дуду заказчика и производитель стандартов тут не при чем. Обязательные стандарты — это директивы там или регламенты у нас, но их настолько мало (в России порядка 20) и к сфере IT они вообще никакого отношения не имеют. Так что можно расслабиться на эту тему.
2. Разочарую — не только за рубежом, но и у нас стандарты разрабатываются не государством, а частными компаниями (комитеты состоят из представителей частных компаний). И именно последние за них платят. Разработка 1 стандарта с нуля стоит организации порядка 2 миллионов рублей, не считая последующей поддержки обновлений. Наше государство само ничего не разрабатывает и денег выделяет только под организационные (процессные) вопросы. Теперь надеюсь понятно почему у нас так мало «свежих» и актуальных гостов и все они как правило — нефть и газ :(
3. Стандарты, во всяком случае зарубежные, разрабатываются группой, в которую входят представители всех заинтересованных сторон, поэтому он не преследует интересы только одной стороны и именно поэтому он и есть соглашение. Количество экспертов, принимающих участие в разработке 1 стандарта, достаточно велико (кстати, их фамилии можно всегда найти или запросить — это открытая как правило информация), в связи с чем стандарт — это сконцентрированный на бумаге опыт работы многих экспертов и многих компаний. Такой опыт самим за короткое время не обрести и не изложить для дальнейшего применения.

2-ое раз уже браться за изучение вопросов написания документации, то подойти к этому надо было как-то шире.
Стандартов на эту тему больше, чем указано. Ко всем приведеным в обсуждения можно добавить стандарты по организацию процесса создания документации, от этого отчасти зависит и качество и полнота — ISO/IEC TR 9294:2005 Information technology — Guidelines for the management of software documentation содержит рекомендуемые стратегии, процедуры, ресурсы и планы, которыми должны заниматься руководители проектов при создании комплекта документов) и
ISO/IEC 15910:1999 Information technology — Software user documentation process — кстати одноименный гост указан в статье — это как раз калька с международного стандарта, правда с заменой многих терминов на вкус переводчика на наши совдеповские, что затрудняет прочтение, поэтому предпочитаю читать в оригинале и вам советую
ISO/IEC TR 12182:1998 Information technology — Categorization of software — здесь можно подчерпнуть под какие типы ПО какие шаблоны документов применимы, т.е. какая структура должна быть у документации вашего ПО
Если вы производите коробочное ПО, то прояснить, что надо писать в этом случае вам поможет ISO 9127:1988 Information processing systems — User documentation and cover information for consumer software packages — старенький, но не потерявший актуальности. И если вы так любите стандарты ISO, то надо ко всем вышеперечисленным еще почитать ISO/IEC 12207:2008 Systems and software engineering — Software life cycle processes, на него ссылаются все ранее указанные стандарты, так как все описанные в них процессы являются частью ЖЦ ПО

Но можно обратиться к другому разработчику — IEEE, у которого не менее богатый набор стандартов:
IEEE 1063-2001 уже указанный является основным, как документ по общим требованиям (минимальным) к пользовательской документации на программные средства широкого применения.
НО еще надо почитать IEEE 829-2008 — IEEE Standard for Software and System Test Documentation, IEEE 730-2002 — IEEE Standard for Software Quality Assurance Plans, IEEE 1012-2004 — IEEE Standard for Software Verification and Validation, IEEE 1028-2008 — IEEE Standard for Software Reviews and Audits и IEEE 830-1998 — IEEE Recommended Practice for Software Requirements Specifications — последние стандарты позволят собрать полную картину по документации.

А есть книга гос. Липаева В.В. ДОКУМЕНТИРОВАНИЕ СЛОЖНЫХ ПРОГРАММНЫХ СРЕДСТВ, которую автор по запросу совершенно официльно отдает в электронном формате. В данной книге есть обзор практически всех указанных стандартов и ряда дополнительных, правда некоторые уже отменены, тем не меннее в ней есть так желаемые всеми шаблоны и рекоммендации и все это в связке со стандартами. Можно начать с нее, потом определиться, какие стандарты вам нужны и покупать только их.
Так что читайте стандарты и применяйте из них только то, что понятно и применимо в вашей компании на вашем уровне развития по принципу разумной достаточности, остальное освоите позже.
одной из целей написания статьи было как раз получение комментариев от матёрых профессионалов)
спасибо!)
многие из перечисленных Вами стандартов я встречала, но отмела как менее относящиеся к документации на выходе. но, пожалуй, для полной выборки надо было и их привести. винюсь.
Я не чувствую себя профессионалом, так как всегда есть то, что я не знаю :) Такая уж быстро меняющаяся эта отрасль. По поводу отметенных стандартов — так сперва и я думала, что мне нужен только шаблон, а остальное ненужная вода, но со временем поняла, что многие вопросы я не могу без правильного процесса осветить, даже не так, не то, что не могу, просто много времени занимают и тяжко все как-то получается. Поэтому занялись процессами. Что и вам желаю. Но если в текущей ситуации вам кажется, что это не надо — видимо так оно и есть :)) честно :)
>Обязательные стандарты — это директивы там или регламенты у нас, но их настолько мало (в России порядка 20) и к сфере IT они вообще никакого отношения не имеют.

А как насчёт сертификации ПО и/или АО? Вроде добровольно, но без сертификации (а ещё получить лицензию нужно) работать нельзя, например, в криптографии, та же ЭЦП в публичных сетях с более-менее стойким ключом шифрования.
Ой, не туда написала, ответ посмотрите плз ниже
Давайте разберемся: что за сертификация ПО? вернее на соответствие чему? с какой целью?
работать нельзя где, или с кем, или в чем? Что значит в криптографии? провайдером или?
Вопрос неточен или даже возможно содержит несколько вопросов. Будьте добры точнее сформулируйте.
Например 1-ФЗ
Статья 5. Использование средств электронной цифровой подписи

2. При создании ключей электронных цифровых подписей для использования в информационной системе общего пользования должны применяться только сертифицированные средства электронной цифровой подписи. Возмещение убытков, причиненных в связи с созданием ключей электронных цифровых подписей несертифицированными средствами электронной цифровой подписи, может быть возложено на создателей и распространителей этих средств в соответствии с законодательством Российской Федерации.
3. Использование несертифицированных средств электронной цифровой подписи и созданных ими ключей электронных цифровых подписей в корпоративных информационных системах федеральных органов государственной власти, органов государственной власти субъектов Российской Федерации и органов местного самоуправления не допускается.

Сертификация производится на соответствие разработанных средств алгоритмам (и форматам?), описанным в ГОСТах, отсутствие закладок и т. п. с целью допустимости использования ЭЦП в системах общего пользования (или корпоративных государственных), как аналога собственноручной подписи и/или печати.

Остальные вопросы опустим, для ясности :)

аа… речь, если я правильно понимаю, идет о выдаче лицензии на осуществление деятельности, связанной с конкретными сертифицированными шифровальными средствами в соответствии с ФЗ РФ «О лицензировании отдельных видов деятельности» (N 158-ФЗ от 25 сентября 1998 года). Да, здесь дело не в стандарте, а исходно в законе, который в свою очередь в части алгоритма криптования ссылается на конкретный стандарт. В таком случае такой стандарт в КОНКРЕТНОЙ ситуации (в связке с данным законом) становится обязательным.

Но тем не менее этот вид лицензирования (по ЗАКОНУ) вам потребуется если вы: а) захотите создавать вышеуказанные средства или б) быть владельцем такого средства. Это вопросы безопасности. Стандарт здесь вторичен.

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

Мы как раз на данный момент практически закончили для одной компании разработку системы удостоверяющего центра. В качестве средства защиты информации использовался VipNet от компании Инфотекс (имеет лицензию), которое мы встроили в свою систему, осуществляющую организацию самого процесса создания, согласования и подписания документов и их хранения, получили отдельный продукт. Владелец этого продукта также прошел лицензирование в ФАПСИ, так как является держателем сертификатов и предоставляет такой сервис, нам (так как работаем со средствами криптографии как с черным ящиком) такая сертификация не нужна. Сертифицирован должен был быть только отдельный модуль, которым и является VipNet.
Аналогично решается ситуация, когда есть система и надо иметь разрешения и лицензии на хранение например персональных данных. Зачем сертифицировать свою систему (кстати все, что пройдет сертификацию менять нельзя, иначе все надо проходить заново), когда хранение данных можно вынести в отдельный модуль под управлением стороннего сертифицированного ПО и радоваться жизни :) Кстати нам это сами сертифицирующие органы подсказали. Иначе можно разориться так как расчет стоимости такого удовольствия идет в пересчете на строки кода, что в нашем случае по скромным подсчетам составляло порядка 1,5 млн рублей. А если учесть, что мы обновляем наше ПО 4 раза в год, то это нам встанет в 6 млн рублей. А зачем?

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

Публикации

Истории