Для чего необходима внешняя программная документация
Единая система программной документации
· СТАНДАРТЫ ДОКУМЕНТИРОВАНИЯ ПРОГРАММНЫХ СРЕДСТВ.
Создание программной документации – важный этап, так как пользователь начинает свое знакомство с программным продуктом именно с документации.
Вообще программную документацию можно разделить по отношению к пользователю на внутреннюю и внешнюю. Внешняя — всевозможные руководства для пользователей, техническое задание, справочники; внутренняя документация — та, которая используется в процессе разработки программного обеспечения и недоступна конечному пользователю (различные внутренние стандарты, комментарии исходного текста, технологии программирования и т.д.).
Общая характеристика состояния в области документирования ПС. Этот комплекс представляет собой систему межгосударственных стандартов стран СНГ (ГОСТ), действующих на территории Российской Федерации на основе межгосударственного соглашения по стандартизации.
Единая система программной документации – это комплекс государственных стандартов, устанавливающих взаимоувязанные правила разработки, оформления и обращения программ и программной документации. Стандарты ЕСПД в основном охватывают ту часть документации, которая создается в процессе разработки ПС, и связаны, по большей части, с документированием функциональных характеристик ПС. В состав ЕСПД входят:
1. основополагающие и организационно-методические стандарты;
2. стандарты, определяющие формы и содержание программных документов, применяемых при обработке данных;
3. стандарты, обеспечивающие автоматизацию разработки программных документов.
ЕСПД нуждается в полном пересмотре на основе стандарта ИСО/МЭК 12207-95 на процессы жизненного цикла ПС
Документирование программ
1.1. Выходные форматы
С выбором конечного формата обычно проблем не возникает, так как целевая операционная система предъявляет свои требования. Так, например, для программ для Windows — это формат скомпилированной справки CHM, для Linux и BSD систем — это man. Общим для всех систем форматом для онлайн справки является html, а для печати — pdf.
Ситуация осложняется в случае, если необходимо иметь документацию в нескольких форматах — для распространения с программой (chm или man), для размещения на сайте (html) и для печати (pdf). При этом возможно, что содержание документации в различных форматах может несколько отличаться. Например, видеофрагменты имеет смысл включать в онлайн документацию, а в печатной версии их нужно заменять на статическое изображение, возможно дополненным qrcode ссылки на видеофрагмент. Кроме того, содержание документов может отличаться и для различных категорий пользователей, версий, комплектов поставки и других факторов.
1.2. Исходные форматы
Несмотря на кажущуюся очевидность необходимости использования специально созданных программ, здесь не все так однозначно.
В зависимости от целевой операционной системы подходы отличаются.
1.2.1. Проприетарные исходные форматы
Так, для создания скомпилированной справки для Windows в формате chm Microsoft предлагает использовать специальный бесплатный компилятор HTML Help Workshop. При этом исходные тексты должны быть подготовлены в формате html (редактор в поставку не входит), а файлы оглавления — в специфическом формате. Никаких средств формирования печатных руководств не предоставляется.
Разумеется, специализированные программы для создания справки (Robohelp, Help&Manual, HelpScribble и им подобные) предоставляют высокий уровень сервиса, обладают возможностью формирования выходных документов в различных форматах и даже в некоторой степени профилировать содержимое.
Однако им присущи следующие недостатки:
На сегодняшний день таких форматов несколько:
Все эти разметки используют некоторый символьный нетеговый набор правил оформления заголовок, иллюстраций и ссылок, предполагающий редактирование в простых текстовых редакторах. Подготовка же пригодного к просмотру вида осуществляется программно как правило на стороне сервера.
Например, Википедия преобразует Wiki-формат в HTML «на лету». Веб-портал системы Git http://github.org также способен показывать документы в разметке Markdown в пригодном для чтения в браузере виде.
1.3. Редакторы
Несмотря на то, что для создания и редактирования исходных текстов достаточно возможностей блокнота, некоторые сервисные функции, такие как проверка правописания и подсветка разметки были бы писателю весьма кстати.
В статье http://www.ixbt.com/soft/markdown-online-2.shtml приведен обзор онлайн-редакторов поддержкой markdown-синтаксиса, а в http://www.ixbt.com/soft/markdown-online-3.shtml приведен обзор пяти настольных редакторов, поддерживающих формат markdown по умолчанию, так сказать «из коробки».
Одним из таких редакторов является MarkdownPad.
1.3.1. MarkdownPad
Рисунок 1. Редактор MarkdownPad 2
Как видно из копии экрана, редактор MarkdownPad 2 поддерживает «живой» предварительный просмотр редактируемого файла с поддержкой синхронной прокрутки исходного текста и результата рендеринга.
При установке на Windows 8 может возникнуть ситуация, когда предварительный просмотр недоступен.
Рисунок 2. Сообщение о крахе системы предварительного просмотра
По заявлению разработчиков http://markdownpad.com/faq.html#livepreview-directx это связано с необходимостью установки специфического SDK веб-рендеринга Awesomium 1.6.6 SDK, который в свою очередь использует DirectX.
Редактор поддерживает подсветку синтаксиса, проверку синтаксиса одного языка (в том числе русского), экспорт в форматы HTML, PDF (только в платной версии). Иными словами, MarkdownPad 2, как и другие специальный редакторы, является хорошим выбором для технического писателя. В тех же случаях, когда пользователю предстоит редактировать файлы различного формата, можно адаптировать свой редактор и для редактирования текстов с markdown-разметкой.
1.3.2. Notepad++
Редактором, в достаточной мере отвечающим этим требованиям, можно считать Notepad++. Проверка правописания многих языков поддерживается с помощью специального плагина. Причем поддерживается проверка текста на нескольких языках одновременно.
Рисунок 3. Редактор Notepad++
Несмотря на простоту правил разметки, автору текстов было бы удобней работать с подсветкой синтаксических элементов. Применительно к Notepad++ в этом поможет проект Markdown Syntax Highlighting for Notepad++, который, по сути, представляет собой конфигурационный файл пользовательского языка Markdown. После его установки текст в редакторе выглядит следующим образом.
Рисунок 4. Редактор Notepad++ с подсветкой элементов разметки markdown
1.4. Quota
Примечательно, что редакторы с поддержкой markdown существуют даже для мобильных платформ. На рисунке приведена копия экрана смартфона с запущенным редактором Quoda Code Editor.
Рисунок 5. Quoda Code Editor — универсальный редактор для Андроид с поддержкой разметки markdown
Следует сказать, что большая часть этой статьи набрана именно в этом редакторе, а уже потом выгружена на компьютер для доработки.
По результатам анализа возможностей языка разметки Markdown и специальных редакторов можно рекомендовать их применение для документирования систем средней сложности.
1.4.1. Открытые теговые форматы
Вместе с тем, для разработки программной документации больших систем следует применять в качестве исходного формата открытый, хорошо документированный формат. В качестве средства формирования — инструмент с широкими возможностями по настройке внешнего вида, профилирования и способностью формировать документы в различных форматах.
Этим требованиям в полной мере отвечают такие системы как DITA и Docbook.
Несмотря на некоторые различия, обе системы имеют много общего:
Следует особо подчеркнуть, что данные системы используют семантическую разметку в исходных документах. Внешний вид же выходного документа определяется правилами и параметрами преобразований. Такой подход позволяет на этапе написания исходных текстов автору не задумываться над типографикой и дизайном, а сосредоточиться исключительно на смысловом содержании.
Вместе с тем практический опыт использования, в частности Docbook, подтвержденный и в ряде публикаций, показал, что и при использовании столь продуманной технологии возникают некоторые сложности:
Естественно, что вышеперечисленные недостатки сдерживают широкое применение XML-ориентированных технологий единого источника.
В случае использования нетеговых форматов для подготовки офлайн или печатной документации необходимо использовать утилиты преобразования. Среди многих конвертеров особого внимания заслуживает программа pandoc.
1.5. Утилита преобразования pandoc
Pandoc представляет собой кроссплатформенную программу с командным интерфейсом, способную преобразовывать тексты в самых разнообразных разметках в многочисленные выходные форматы.
Так, например с использованием pandoc можно конвертировать исходные документы в разметках ASCIIdoc, Wiki, Markdown в HTML. Если установить LaTex, то становится возможным получение и PDF.
Так, например, преобразование исходного текста этой статьи в html формат можно выполнить следующей командой:
Результатом будет готовый html-файл:
Рисунок 6. HTML-документ, сформированный из Markdown утилитой pandoc
За свою универсальность программа образно названа автором «швейцарским армейским ножом».
Действительно, pandoc справляется с конвертированием без каких-либо потерь информации. При конвертировании из формата MarkDown поддерживается чтение трех параметров метаданных — заголовка, автора и даты документа. Поддерживается также передача параметров командной строки для установки некоторых специфических свойств, например языка документа. Есть возможность задать свой шаблон выходного документа, до некоторой степени видоизменяя его.
Рисунок 7. HTML-документ, сформированный pandoc с использованием заголовочного файла со ссылками на стили
Как видно из примера, заголовки приобрели свой стиль, а внешние ссылки стали открываться в новой вкладке браузера.
Вышеописанные возможности формата делают оправданным использования разметки Markdown для документирования относительно небольших программных систем, к оформлению которых не предъявляется требований ГОСТ, что и доказывается ее широким использованием в системе Git.
Что же касается больших систем с обширной и сложной документацией, то для ее создания видится применение системы единого источника Docbook. Могут иметь место и переходные случаи, когда масштаб проект проявляется не сразу.
1.6. Docbook
Сложность создания исходных XML-источников можно преодолеть путем использования исходных текстов в формате Markdown с последующим их конвертированием в Docbook. Такое преобразование поддерживается утилитой pandoc. Так, команда
Использование заголовочного файла h.xml (можно просто пустого) необходимо для корректной обработки метатегов и формирования статьи.
Рисунок 8. Сформированная статья в XML-редакторе
Следует отметить несколько дополнительных требований к разметки markdown, которая будет использована для преобразования в docbook:
Однако выходной текст формируется в устаревшем формате Docbook 4 версии, в то время как современная 5 версия предоставляет существенно более богатые возможности по семантической разметке.
Для преобразования текста из 4 в 5 версию можно воспользоваться специальным преобразованием db4-upgrade.xsl, входящим в комплект поставки Docbook.
Полученный таким образом xml файл схемы docbook 5 можно использовать при формировании единого источника.
Рисунок 9. Cтатья схемы в XML-редакторе в режиме автора
Описанная цепочка преобразований может показаться на первый взгляд длинной и неоправданно сложной. Однако освоив один раз необходимые инструменты и разработав для часто выполняемых задач командные файлы (скрипты) можно сэкономить значительное количество времени в дальнейшем.
Следует особо подчеркнуть, что технология единого источника обладает ярко выраженным кумулятивным эффектом. Начальные временные затраты на разработку типовых неоднократно используемых фрагментов текста окупаются при их использовании в последующих проектах. Именно это качество делает особо привлекательным технологию единого источника при документировании серийных программных систем.
Набор преобразований Docbook поддерживает формирование документов в HTML со стилями, PDF для печати так сказать «из коробки».
Внешний вид выходных документов может быть до определенной степени настроен с помощью параметров. Полученные файл формата FO-XSL pandoc5.fo является промежуточным и нужен для построения конечного PDF.
Немаловажна и возможность автоматического формирования оглавления, списка иллюстраций, листингов, таблиц, индексного указателя, глоссария терминов и списка литературы.
При большом количестве документов в составе пакета также возможно создание отдельного списка с возможностью автоматического формирования правильно оформленных ссылок на них. В случае же подготовки типографского макета руководства с учетом особых требований, например ГОСТ, необходимо разработать дополнительные xsl для форматов обычных страниц, титульной и финальной страницы.
Программная документация и ее разновидности
Ниже мы рассмотрим понятие программной документации и ее разновидности.
Под программной документацией понимают различные виды документов в печатном и электронном виде, содержащих информацию о разработке, изготовлении, испытаниях, эксплуатации и сопровождении программных изделий.
В России разработку программной документации принято проводить в соответствии с требованиями ЕСПД – единой системы программной документации.
С точки зрения ЕСПД программы разделают на следующие виды (ГОСТ 19.101):
Компонент – программа, рассматриваемая как единое целое, выполняющая законченную функцию и применяемая самостоятельно или в составе комплекса
Комплекс – программа, состоящая из двух или более компонентов и (или) комплексов, выполняющих взаимосвязанные функции, и применяемая самостоятельно или в составе другого комплекса
Также в ГОСТ 19.101 упоминается и такое важное понятие как «программное изделие», в п. 1.3 данного стандарта указано следующее: «документация, разработанная на программу, может использоваться для реализации и передачи программы на носителях данных, а также для изготовления программного изделия». А в соответствии с ГОСТ 19.004 программное изделие – это «Программа на носителе данных, являющаяся продуктом промышленного производства».
Отдельно необходимо сказать несколько слов о разработке технических условий на программу (а если точнее на программное изделие, этот термин мы поясняли немного выше). В том же ГОСТ 19-101 достаточно немного про них написано, а именно «2.7. На этапе разработки и утверждения технического задания определяют необходимость составления технических условий, содержащих требования к изготовлению, контролю и приемке программы. Технические условия разрабатывают на стадии «Рабочий проект».
Т.е. получается, что если в техническом задании нет требований по разработке ТУ на программу, то вроде бы можно и не разрабатывать. Однако довольно часто этот документ все же разрабатывают т.к. он достаточно полезен при изготовлении, контроле, приемке, а также и при сертификации программных изделий, особенно актуальна разработка технических условий на программу при работах в интересах государственного Заказчика (МО РФ и др.). Необходимо упомянуть и следующую особенность – в системе ЕСПД не существует стандарта, предъявляющего требования к разделам и содержанию ТУ на программное изделие. Обычно при разработке ТУ руководствуются требованиями «конструкторского» ГОСТ 2.114, применяя его основные требования, оформление же делают в соответствии с ГОСТ 19-106 (т.е. без рамки как в КД).
Также необходимо упомянуть о том, что в зависимости от способа выполнения и характера применения программные документы подразделяются на подлинник, дубликат и копию (ГОСТ 2.102), предназначенные для разработки, сопровождения и эксплуатации программы.
Виды программной документации
ДОКУМЕНТИРОВАНИЕ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ, ЕСПД
Любая программа должна снабжаться программной документацией. Документирование программ регламентируется стандартами Единой системы программной документации (ЕСПД) вне зависимости от назначения и области применения.
Единая система программнной документации – комплекс государственных стандартов, устанавливающих взаимоувязанные правила разработки, офомления и обращения программ и программной документации.
Виды программ и программных документов для ЭВМ комплексов и систем независимо от их назначения и области применения установлены ГОСТ 19.101-77 и ГОСТ 19781-90.
ПРОГРАММА – это данные, предназначенные для управления конкретными компонентами системы обработки информации в целях реализации определенного алгоритма
Программы подразделяют на два вида: компонент и комплекс.
(или) комплексов, выполняющих взаимосвязанные функции и применяемая самостоятельно или в составе другого комплекса.
К программным документам относят документы, содержащие сведения, необходимые для:
4) эксплуатации программ.
Виды ПД и их содержание, правила оформления документов и их частей устанавливаются соответствующими стандартами ЕСПД.
Для МАЛЫХ АВТОНОМНЫХ программ в качестве документации используется в основном текст оттранслированной программы на языке программирования. Сопровождение таких программ не их разработчиками практически невозможно.
Для БОЛЬШИХ ПРОЕКТОВ программ необходима полная документация.
Для чего нужна документация?
Документация на ПС решает следующие задачи:
1) формализует методы решения задач, состав используемой и выдаваемой информации;
2) способствует резкому сокращению количества ошибок и тем самым облегчает отладку;
3) позволяет вносить и учитывать изменения в программах;
4) обеспечивает возможность замены первичного разработчика программы другим без повторения ранее выполненной работы;
5) позволяет изучать, эксплуатировать и модернизировать ПО;
6) позволяет использовать разработанные компоненты и комплексы
программ в разных ПС и применять сборочное программирование.
Документацию не очень хочется писать. Но без документации кроме всего прочего:
1) можно занести вирус;
2) режимы работы исследуются вслепую методом проб и ошибок;
3) неизвестно что делать в непредвиденных случаях.
Документация должна разрабатываться с самого начала проектирования ПО и непрерывно уточняться для обеспечения полного соответствия программному изделию.
Виды программной документации:
К такой документации относятся документы, которыми руководствуется пользователь при:
— инсталяции ПС (при установке ПС с соответствующей настройкой на среду применения ПС);
— при применении ПС для решения своих задач и при управлении ПС (например, когда данное ПС взаимодействует с другими системами).
Эти документы частично затрагивают вопросы сопровождения ПС, но не касаются вопросов, связанных с модификацией программ.
В связи с этим следует различать две категории пользователей ПС: ординарных пользователей ПС и администраторов ПС. Ординарный пользователь ПС (end-user) использует ПС для решения своих задач (в своей предметной области). Это может быть инженер, проектирующий техническое устройство, или кассир, продающий железнодорожные билеты с помощью ПС. Он может и не знать многих деталей работы компьютера или принципов программирования. Администратор ПС (system administrator) управляет использованием ПС ординарными пользователями и осуществляет сопровождение ПС, не связанное с модификацией программ. Например, он может регулировать права доступа к ПС между ординарными пользователями, поддерживать связь с поставщиками ПС или выполнять определенные действия, чтобы поддерживать ПС в рабочем состоянии, если оно включено как часть в другую систему.
ТЕХНОЛОГИЧЕСКАЯ документация кроме эксплуатационной документации включает ряд документов, необходимых для развития и сопровождения ПО в течение всего жизненного цикла.
ИССЛЕДОВАТЕЛЬСКАЯ документация предназначена для анализа жизненного цикла ПО. Основная ее задача состоит в фиксировании и обобщении характеристик жизненного цикла ПО.
1) программма работает, но ни кто не знает как она это делает
Лекция 5. Общая характеристика состояния в области документирования программных средств
Создание программной документации — важный этап, так как пользователь начинает свое знакомство с программным продуктом именно с документации. Составлением программной документации обычно занимаются специальные люди — технические писатели (иногда программную документацию пишут сами программисты или аналитики).
Грамотно составленный (точнее, созданный) пакет программной документации избавит вас от многих неприятностей. В частности, избавиться от назойливых вопросов и необоснованных претензий можно, просто отослав пользователя к документации. Это касается, прежде всего, важнейшего документа — Технического задания.
Вообще программную документацию можно разделить по отношению к пользователю на внутреннюю и внешнюю. Внешняя — всевозможные руководства для пользователей, техническое задание, справочники; внутренняя документация — та, которая используется в процессе разработки программного обеспечения и недоступна конечному пользователю (различные внутренние стандарты, комментарии исходного текста, технологии программирования и т.д.).
Когда программист-разработчик получает в той или иной форме задание на программирование, перед ним, перед руководителем проекта и перед всей проектной группой встают вопросы:
· Что должно быть сделано, кроме собственно программы?
· Что и как должно быть оформлено в виде документации?
· Что передавать пользователям, а что — службе сопровождения?
· Как управлять всем этим процессом?
· Что должно входить в само задание на программирование?
На эти и другие вопросы когда-то отвечали государственные стандарты на программную документацию — комплекс стандартов 19-й серии ГОСТ ЕСПД. Но уже тогда у программистов была масса претензий к этим стандартам.
Основу отечественной нормативной базы в области документирования ПС составляет комплекс стандартов Единой системы программной документации (ЕСПД). Основная и большая часть комплекса ЕСПД была разработана в 70-е и 80-е годы 20 века. Сейчас этот комплекс представляет собой систему межгосударственных стандартов стран СНГ (ГОСТ), действующих на территории Российской Федерации на основе межгосударственного соглашения по стандартизации.
Единая система программной документации — это комплекс государственных стандартов, устанавливающих взаимоувязанные правила разработки, оформления и обращения программ и программной документации.
Стандарты ЕСПД в основном охватывают ту часть документации, которая создается в процессе разработки ПС, и связаны, по большей части, с документированием функциональных характеристик ПС.
В состав ЕСПД входят:
· основополагающие и организационно-методические стандарты;
· стандарты, определяющие формы и содержание программных
документов, применяемых при обработке данных;
· стандарты, обеспечивающие автоматизацию разработки программных документов.
Большая часть стандартов ЕСПД морально устарела. ЕСПД нуждается в полном пересмотре на основе стандарта ИСО/МЭК 12207-95 на процессы жизненного цикла ПС.
· Тем не менее, до пересмотра всего комплекса многие стандарты могут с пользой применяться в практике документирования ПС.
Надо сказать, что наряду с комплексом ЕСПД официальная нормативная база РФ в области документирования ПС и в смежных областях включает ряд перспективных стандартов (отечественного, межгосударственного и международного уровней).
Международный стандарт ISO/IEC 12207:1995 на организацию ЖЦ продуктов программного обеспечения (ПО), казалось бы, весьма неконкретный, но вполне новый и отчасти «модный» стандарт.
Дата добавления: 2015-10-13 ; просмотров: 1714 ; ЗАКАЗАТЬ НАПИСАНИЕ РАБОТЫ