Разработка технической документации и технические писатели Технические писатели и разработка технической документации технические писатели в Телеграм 

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1
Ответить
RSS
О том, какими бывают стандарты на разработку технической документации, стандарты на разработку технической документации
 
Интересная статья с хабра, думаю многим окажется полезной:

Документация – такая штука, к которой мало кто питает тёплые чувства: скучно, занудно, однообразно. И, тем не менее, иногда не возникает сомнений в её необходимости: ведь кому-то после вас этим пользоваться или, тем паче, модифицировать. И тогда появляется вопрос: как сделать документацию правильно?

Существует тьма статей на тему «как писать документацию», но если вы решили взяться за неё в первый раз, то в новой для вас области не сразу понятно, дело ли пишет автор, или отсебятину выдумывает.

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

Кто-то может сказать «а-а, стандарты! они ещё более адово скучные, чем сама документация!». Ну, не будем врать, есть немного  :)  Но если у вас документ в электронном формате – найти необходимое не составляет труда. И кроме того, ну надо же размочить раздел стандарты уже, а то висит пустой, даже обидно.

Наши стандарты

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

ГОСТ Р ИСО 9127-94 «Документация пользователя и информация на упаковке для потребительских программных пакетов» – наиболее приглянувшийся мне стандарт из наших. Довольно кратко (весь документ – около 20 страниц) указаны основные требования к составу и содержанию документации пользователя.

ГОСТ Р ИСО/МЭК 15910-2002 «Процесс создания документации пользователя программного средства» — стандарт больше отвечает не на вопрос «Что» должно быть в документе, а «Как» должен создаваться документ. Дополнительно есть подробное описание стиля документа с примером – довольно удобная штука для создания шаблона: один раз запариваешься (и забиваешь в шаблон всё: от выравнивания до формата подписей рисунков), а потом клепаешь документы все одного вида, а не с заголовками разного шрифта.

ГОСТ-ы серии 19.хх – серия ЕСПД, страсть, какая древняя (в среднем, документы созданы в 78-м году), но зато такие же лаконичные, как в ГОСТ 9127, требования ко многим видам документов.
Посмотреть

ГОСТ 34.602-89 «Техническое задание на создание автоматизированной системы» — стандарт на ТЗ.

Посмотреть 34 ГОСТ

Буржуйские стандарты

Не было предела моему возмущению, когда я узнала, что международные стандарты не бесплатные. Это как правила дорожного движения сделать платными. Но в принципе, может и резонно: организации-то не государственные. Хотят – могут и деньги брать за свою работу. К счастью, многие стандарты можно скачать по-привычному, по-пиратски.

IEEE Std 1063-2001 «IEEE Standard for Software User Documentation» — в документе обозначены требования к структуре, содержимому и формату инструкций пользователя.
Официальная страница.

IEEE Std 1016-1998 «IEEE Recommended Practice for Software Design Descriptions» — рекомендации к документам, описывающим архитектуру программного обеспечения, то бишь к техническому описанию.

Особливо понравилась табличка-экстракт основного содержания документа


ISO/IEC FDIS 18019:2004 «Guidelines for the design and preparation of user documentation for application software» — рекомендации по созданию документации пользователя. Так сказать, советы «хозяйке на заметку». Довольно приятное руководство с большим количеством примеров (имхо, больше подходит для чтения до или в самом начале создания документации, так как подходит к процессу основательно, от самого планирования). Также в приложениях есть чеклисты «что не забыть сделать в процессе разработки документации» и «что должно быть в документе»

ISO/IEC 26514:2008 «Requirements for designers and developers of user documentation» — довольно свежий и, судя по содержанию, полезный документ. Но, как раз, видимо, ввиду его свежести, этот стандарт нигде не найти бесплатно. По крайней мере, мне этого сделать не удалось.
Официальная страница.

Это были стандарты, наиболее тесно связанные с документированием. Они могут пригодиться начинающему техническому писателю
 
Что можно сказать... Упущена пара важных документов - РД 50-34.698-90 и ГОСТ 28195. Можно добавить, что IEEE Std 1063-2001 намного "слабее" ГОСТ 19.ххх-7х. Буржуи отстали от нас на 20 лет по научно-техническому уровню :)
 
Цитата
Что можно сказать... Упущена пара важных документов - РД 50-34.698-90 и ГОСТ 28195. Можно добавить, что IEEE Std 1063-2001 намного "слабее" ГОСТ 19.ххх-7х. Буржуи отстали от нас на 20 лет по научно-техническому уровню :)
спасибо за дополнение! действительно их даже не упомянули
 
Есть статья со сравнительным анализом ай-яй-яй и ГОСТ 19  :)
 
Цитата
Есть статья со сравнительным анализом ай-яй-яй и ГОСТ 19 :)
про 19 есть, цитирую:
Цитата
ГОСТ-ы серии 19.хх – серия ЕСПД, страсть, какая древняя


Цитата
Есть статья со сравнительным анализом

А что  за статья? Можно ее в студию?
 
 
 
 
 
 
Orlan188 а есть еще какие-нибудь такие полезные штуки как вы выложили? Мы бы их на сайте разместили в разделе Сервисы, для помощи техническим писателям?
 
Цитата
''writer'' пишет:
Orlan188 а есть еще какие-нибудь такие полезные штуки как вы выложили? Мы бы их на сайте разместили в разделе Сервисы, для помощи техническим писателям?
Полно, эти схемы из учебных курсов, в которых степень моего участия 1/3, схемы мои.
Изменено: Orlan188 - 04.07.2013 17:47:22
 
Цитата
Цитата
Orlan188 а есть еще какие-нибудь такие полезные штуки как вы выложили? Мы бы их на сайте разместили в разделе Сервисы, для помощи техническим писателям?
Orlan188 пишет: Полно, эти схемы из учебных курсов, в которых степень моего участия 1/3, схемы мои.
Схемы получили, скоро выложим на сайт. Спасибо!
Страницы: 1
Ответить
Читают тему
Форма ответов
 
Текст сообщения*
Загрузить файл или картинкуПеретащить с помощью Drag'n'drop
Перетащите файлы
Ничего не найдено
Отправить Отменить