Оглавление

Введение 5

Общие принципы составления технической документации к программному продукту 6

Техническая документация и ее состав 6

Требования предприятия 9

Коллективная разработка 9

Мультиязычность 10

Многовариантное представление документации 12

Принцип единого источника 13

Разделение содержания от его представления 16

Анализ средств разработки технической документации 18

Средства разработки, основанные на XML 18

DocBook 20

DITA 29

Инструментарий 37

Порядок формирования документа 38

Применение систем управления версиями 40

Централизованные системы управления версиями 41

CVS, Subversion 44

Децентрализованные системы управления версиями 47

Git 49

Mercurial 50

Организационно-экономический раздел 52

Безопасность жизнедеятельности 59

Заключение 69

Библиографический список 71

Приложения 73

 

Внимание!

Диплом № 2127. Это ОЗНАКОМИТЕЛЬНАЯ ВЕРСИЯ дипломной работы, цена оригинала 500 рублей. Оформлен в программе Microsoft Word. 

Оплата. Контакты.

Введение

 

Документация часто рассматривает нечто, разрабатываемое после создания конкретного программного средства. Однако с точки зрения качества разработки программной документации она должна рассматриваться как неотъемлемая часть процесса создания данного программного средства. При надлежащем подходе к данной проблеме требуется достаточно сложная работа по планированию документирования. Целью настоящего стандарта является стимулирование разработчиков программных средств к надлежащему использованию процесса документирования. Стандарт также представляет пользователям метод определения надлежащего применения процесса документирования при создании конкретного программного средства.

Основной работой по настоящему стандарту является создание комплексного плана разработки документации, реализация которого обеспечивает лучшее документирование программного средства. Для соответствия настоящему стандарту данный план должен включать в себя требования (спецификацию) к стилю оформления документов. Настоящий стандарт не определяет состав данных требований (то есть компоновку конкретного документа или используемый шрифт), но устанавливает их диапазон. Стандарт также определяет виды информации, представляемой заказчиком разработчику документации (документатору) для проверяющих и распространяющих документацию.

 

Общие принципы составления технической документации к программному продукту

Техническая документация и ее состав

 

Документом называется связный, единый, завершенный текст, соотнесенный с одним из видов документов: руководством пользователя, справочником пользователя и т. д.; документация — понятие собирательное, она состоит из ряда документов. Однако часто бывает так, что документация к программному продукту вся собрана под одной обложкой и представляет собой интегрированный документ. Далее мы будем говорить о главах и разделах документации, имея в виду этот единый документ.

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

Точность выражений — одна из важнейших черт, отличающих хорошую документацию от плохой. Оттенки значений слов и выражений играют большую роль в нашем восприятии, даже если мы не отслеживаем их на сознательном уровне. Если мы хотим сказать в целом обо всей деятельности, которой занимаетемся, мы говорим: «подготовка технической документации к программному обеспечению». Если мы говорим в целом о работе по какому-то отдельному продукту: «подготовка технической документации к программному продукту». Не рекомендуется говорить: «Х — это программное обеспечение»; лучше сказать: «Х — это программа» или «Х — это программный комплекс».

В состав технической документации входят две стержневые части, которые мы будем называть соответственно руководством пользователя и справочником пользователя, или коротко: руководством и справочником (по аналогии с английскими словосочетаниями User’s Guide и User’s Reference). Они могут быть оформлены в виде отдельных документов (для крупных программных продуктов), а могут, напротив, существовать в интегрированном виде. Между ними даже может не быть четкой границы: единый текст способен совмещать в себе черты руководства и черты справочника. Руководство и справочник — это не столько части документации, сколько понятия, которые воплощают собой два подхода к описанию программного продукта.

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

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

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

Особняком стоит еще один тип документа — справочный гипертекст, на основе которого функционирует система справок по программе (Help). Гипертекст, как правило, пишется на основе готовой «бумажной» документации; в то же время его ни в коем случае не следует рассматривать лишь как слегка модифицированный обычный текст. Отдельные части гипертекста связаны настолько сложной системой реализуемых в интерактивном режиме взаимных ссылок, что необходимо уже говорить о гипертексте как о совершенно специфическом средстве передачи информации со своими законами, отличными от законов обычного текста. Эта специфика гипертекста выражается, что очень важно для нас, в кардинальном расширении возможностей передачи информации по сравнению с обычным текстом.

Мы очертили круг основных компонентов, из которых складывается готовая документация, — в том виде, в каком с ней встречается пользователь (и в каком с ней наверняка встречались и Вы). Однако разработчик документации начинает, разумеется, не с готовой книжки, а с чистой рабочей панели текстового редактора. Наша задача не столько в том, чтобы рассказать, как выглядит документация, сколько в том, чтобы дать конкретные рекомендации по ее эффективной разработке. Всем известно, какие проблемы возникают в процессе написания связного текста большого объема — как приступить к работе, с чего начать, как расположить материал.

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

• Какие цели преследует разработчик документации к программному продукту?

• Какими средствами он располагает для достижения своих целей?

 

Требования предприятия

Коллективная разработка

 

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

Одним из требований компании «Системы Папилон» к процессу разработки технической документации к программным и аппаратным комплексам является поддержка коллективной разработки.

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

 

Мультиязычность

 

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

Процесс разработки мультиязычной документации к ПО в компании «Системы Папилон» выглядит так:

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

2. Сотрудники группы разработки технической документации разрабатывают документацию на русском языке. Разработка осуществляется в зависимости от реализации мультиязычности в используемом средстве разработки и с максимально возможным учётом специфики языка перевода (также учитываются гайдлайны для перевода).

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

4. Документация выпускается. Ошибки перевода, замеченные в процессе её эксплуатации, фиксируются и передаются группе переводчиков.

5. Процесс повторяется.

 

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

 

Многовариантное представление документации

 

Программное обеспечение, выпускающееся компанией «Системы Папилон», разрабатывается в соответствии со специфическими требованиями клиентов. Примером таких требований может являться кроссплатформенность ПО (работа программ в различных операционных системах и средах — например, в GNU/Linux и Microsoft Windows).

Соответсвенно, и документация к программному обеспечению должна соответствовать таким требованиям.

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

• Файл контекстной справки Microsoft Compiled HTML Help (CHM)

• Файл контекстной справки GNU/Linux

• Файл в формате Portable Document Format (PDF) — кроссплатформенном формате электронных документов, готовом для печати

• Документация в формате HTML, доступном через Internet

• Отпечатанная типографским способом документация

Соответствие требованию многовариантного представления достигается за счёт отделения содержания документации от её представления с помощью языков логической разметки и её дальнейшего преобразования с помощью XSLT и XSL-FO.

Например, Разделение контента и форматирования в XML формате Docbook позволяет трансформировать один и тот же документ во множество различных форматов (например, включая, но не ограничиваясь: PDF, RTF, HTML и Eclipse Help). Стандартная поставка Docbook включает примеры скриптов и таблиц стилей для трансформации в PDF, HTML и Eclipse Help.

 

Принцип единого источника

 

Модульный подход укоренился в программировании много лет назад. Никто не набирает один и тот же программный код многократно, а злоупотребление командами текстового редактора «Copy» и «Paste» программисты, несомненно, признают грубой работой. Если программа в разных ситуациях должна выполнять одни и те же действия, их оформляют в виде функций или процедур. Если действия одинаковы в общем, но различаются в зависимости от конкретной ситуации, то программист предусматривает возможность передать функции или процедуре определенные аргументы.

В технической документации повтор — явление не менее редкое, чем в программе. Приходится описывать сходные функции программ и систем, сходные экранные формы, сходные действия пользователей. Описания одних и тех же объектов приходится полностью или частично дублировать в разных документах. Поскольку материал, из которого состоит техническая документация, — текст на естественном языке, применить к нему модульный подход оказывается сложнее, чем к программному коду. В нем хватает нерегулярностей, обусловленных лексическими и грамматическими исключениями, сложившимися традициями, соображениями стилистики и эстетики. Многие разработчики документации, скрепя сердце, делают то, что было бы позором для любого программиста: «копипейстят» собственный текст и при необходимости вручную правят его, приспосабливая к очередному контексту. Надо ли долго объяснять, почему это повышает трудоемкость разработки и особенно сопровождения документации, а также приводит к многочисленным ошибкам?

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

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

Принцип единого источника в документировании, как и модульный принцип в программировании, помогает организовать работу коллектива соавторов, распределив между ними более-менее изолированные подзадачи. Таким образом, единый источник — это не только техническое, но еще и организационное решение. Взаимодействие между участниками разработки технической документации тоже может быть автоматизировано. Крупные интегрированные среды для автоматизации документирования, такие, как AuthorIT, SiberSafe, RoboHELP [6], предоставляют для этого различные средства: управления правами доступа, версионный контроль, планирование работ и т.п. Возможно, части именно ради этих возможностей их и приобретают. Но все это относится, скорее, к документообороту отдела документирования или техническому документообороту проекта, важным темам, которым стоило бы посвятить отдельную статью и не одну. Надеюсь, мы их еще обязательно обсудим.

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

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

 

Разделение содержания от его представления

Освобождение текста от оформления

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

К разоружению есть несколько мотивов.

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

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

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

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

Как разделить текст и оформление, известно давно. Для этого используют т.н. стили. Однако разные инструменты и технологии предусматривают разные степени и формы такого разделения. Так, в текстовом процессоре Microsoft Word стили абзацев, строк и списков можно вынести в шаблон, но формат бумаги, поля, колонтитулы и другие параметры страницы всегда остаются принадлежностью конкретного документа. Технология CSS позволяет хранить многие свойства оформления вне HTML-документа, но не лишает автора возможности применять форматирование непосредственно (хотя бы с помощью атрибута style). Некоторые решения, основанные на XML и XSLT, в том числе, DocBook/XML, позволяют полностью лишить автора контроля над оформлением документа.

Итак, используя подходящие механизмы применения оформления к тексту и подходящие конверторы, мы можем без всяких компромиссов предоставить аудитории текст в тех видах и формах, которые считаем уместными. Но это будет один и тот же текст, повторенный слово в слово. Что далеко не всегда хорошо. В некоторых случаях бывает нужно на основе одного корпуса текстов изготовить несколько разных документов или даже несколько разных комплектов документов.

 

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

Средства разработки, основанные на XML

Об XML-технологиях написаны библиотеки учебников и монографий [4, 10, 11, 12, 13, 14, 15], не счесть посвященных им статей в периодике и ресурсов в Интернете. Здесь мы расскажем о них предельно кратко для тех, кто совсем не представляет себе, что это такое, а также чтобы далее не засорять текст ссылками на известные факты.

Проблема унификации форматов данных, вероятно, возникла вместе с первыми ЭВМ, это «родовая травма» информационных технологий. Противоборствуют две тенденции: с одной стороны, каждая задача требует средств обработки и хранения специфичных для нее данных, с другой стороны, необходимость обмена данными требует эти средства унифицировать. Поиски разумного компромисса на этом поле время от времени приводили к появлению более или менее удачных универсальных форматов. В основном они предназначались для представления данных определенного характера: графики, текста, звука, географических карт, баз данных и т. п. Поскольку разработчики действовали разрозненно, форматы не только получались разными, но и в основе имели разные принципы организации данных. Приходилось для каждого формата разрабатывать отдельные механизмы обработки, что не экономично само по себе и вдвойне не экономично, если в одном приложении обрабатываются данные разных форматов.

Вряд ли кто-нибудь строил иллюзии относительно возможности разработки универсального, энциклопедического формата, пригодного для представления любых мыслимых данных. Выходом из положения виделось создание абстрактного формата форматов, который позволял бы описывать сколь угодно специфичные форматы, но такие, чтобы синтаксическое родство между ними было достаточно сильно и допускало реализацию общих механизмов обработки. В качестве решения этой задачи в 1989 г. был предложен язык Standard Generalized Markup Language (SGML), а позже, в 1998 г., более простой и технологичный eXtensible Markup Language (XML) [10].

Не вдаваясь в подробности, скажем, что XML — это язык описания языков разметки с общим синтаксисом и разными словарями. Свобода словаря позволяет создавать конкретные специализированные XML-языки, а общность синтаксиса — обрабатывать произвольные XML-данные одними и теми же программами. Если вы изучаете лягушек, то вам никто не мешает придумать специальный формат структурированного представления информации о них. Для ввода данных вы сможете использовать любой понравившейся вам XML-редактор, а для публикации на своем веб-сайте любой XSLT-процессор. Одновременно у вас есть возможность автоматически загружать данные в базу данных и находить там нужные сведения по существенным для предметной области признакам.

Хороший принцип в сочетании с удачной реализацией привели к взрывообразному росту XML-технологий. Количество программ для работы с XML-данными и специалистов, владеющих этой областью, увеличивается ежедневно. Во многие прикладные пакеты встраивается возможность импорта и экспорта XML-данных. Не возьмемся делать прогнозы, но, судя по всему, решениям, основанным на XML, технологическая и кадровая изоляция в обозримом будущем не угрожает.

 

DocBook

 

Основой технологической платформы DocBook/XML служит одноименный проблемно-ориентированный язык разметки [1]. Он предназначен для записи текста технической документации на программы, алгоритмические языки, компьютерное оборудование и другие решения в области информационных технологий, чем принципиально отличается от большинства форматов хранения текстовых данных (но не XML-языков!). В языке DocBook/XML предусмотрены средства описания фрагментов, свойственных технической документации, например, специальными элементами полагается выделять названия элементов интерфейса, обозначения клавиш, имена переменных, термины, различные врезки (замечания, подсказки, предупреждения), листинги, описания выполняемых пользователем процедур. Разметка, задаваемая языком DocBook/XML, носит преимущественно функциональный характер: автору предписано указывать роль, которую тот или иной фрагмент играет в тексте, а не способ его внешнего оформления. Такой подход сковывает автора, зато позволяет добиться заведомой независимости содержания и оформления выходного документа и унифицировать некоторые важные качества стиля изложения при работе нескольких авторов в одном проекте.

Язык разметки DocBook имеет долгую по «компьютерным» меркам историю. Его первая версия, опиравшаяся на SGML, была создана еще в 1991 г. совместными усилиями компаний O’Reilly & Associates и HaL Computer Systems [1]. Версия на базе XML увидела свет в 1998 г., тогда же язык перешел в ведение специально образованного технического комитета консорциума OASIS [2]. В состав этого технического комитета входят всемирно известные компании, в том числе, Hewlett-Packard и IBM. Сегодня язык разметки DocBook/XML применяется разработчиками технической документации во всем мире.

Спецификация XInclude. Языки XPointer и XPath

 

Язык разметки XInclude [13], основанный на XML, предназначен для создания внутри XML-документа включающих ссылок на другие XML-документы или их узлы. Адресоваться к включаемым документам можно по URI. Для указания на узлы XML-документов используются языки XPointer и XPath [4, 10, 13, 14, 15], позволяющие формулировать запросы к XML-данным. Запросы могут содержать разнообразные условия: навигационные указания, проверки и логические функции. Результатом запроса в общем случае является набор узлов, удовлетворяющих его условиям. Средствами языка XInclude можно также потребовать включения в XML-документ ‘плоского’ текстового файла, что особенно полезно при цитировании листингов.

Язык описания графов пакета GRAPHVIZ

Пакет GRAPHVIZ (проект компании AT&T) интересен тем, что позволяет применить принцип единого источника к графическим схемам. Автор описывает схему на специальном языке разметки, а потом с помощью конвертора формирует графический файл. По синтаксису этот язык напоминает язык программирования Си, но проще и менее строг. Лучше всего он приспособлен для описания графов, так как предлагает оперировать вершинами и соединительными стрелками. Вершинам и стрелкам можно придавать разные формы; предусмотрены средства для взаимного позиционирования вершин.

Открытость языков разметки

Мы упомянули несколько языков, наиболее интересных и важных с точки зрения целей настоящего обзора. Многообразие языков разметки невероятно велико. Так, для векторной графики существует язык SVG, для математических формул MathML, для отформатированного текста XSL-FO; перечислять здесь все языки разметки нет ни возможности, ни надобности. Главное, что они складываются в открытую технологию, допускающую решение любой осмысленной (не все-таки не фантастической) задачи за соразмерное время при соразмерных затратах. В этом их преимущество перед проприетарными продуктами, которые могут предоставлять богатые возможности, но не допускать выхода за их пределы. Даже если сегодня их возможности кажутся нам избыточными, где гарантия, что завтра, через месяц или через год нам не потребуется какая-нибудь важная мелочь, которую разработчики не реализовали и даже не собираются?

Инструментарий и порядок создания документов

Редакторы входных документов

Для набора текста входного документа могут применяться разные программы, от обыкновенного «Блокнота» до развитых XML-редакторов. Поскольку требования к формату входного документа определяются спецификациями используемых языков разметки, выбор редактора перестает быть важным вопросом, который необходимо решить на уровне проекта. Каждый автор может работать в том редакторе, который ему удобен.

По отношению к задаче набора текста в формате DocBook/XML существующие сегодня редакторы можно разделить на следующие группы:

• обычные текстовые редакторы;

• XML-редакторы с интерфейсом текстового процессора;

• XML-редакторы, упрощающие набор разметки.

Обычные текстовые редакторы позволяют набирать текст, интерпретируемый ими как простая последовательность символов и строк. Все заботы о его структуре перекладываются на автора. Функциональность текстовых редакторов, если она шире, чем у редактора «Блокнот», обычно связана с набором символов в разных кодировках, поиском и заменой строк, обработкой нескольких текстовых файлов, а также макросами, ускоряющими ввод часто повторяющихся фрагментов.

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

XML-редакторы с интерфейсом текстового процессора предлагают пользователям, не желающим вникать в синтаксис языков разметки, более-менее привычную среду для ввода и правки текста (рис. 1). Обычно они позволяют редактировать любые XML-документы, но ориентированы на популярные форматы, в том числе, DocBook/XML, DITA, XHTML, TEI.

 

Рисунок 1 — Редактор XMLmind

Такие редакторы — большое подспорье для авторов, начинающих пользоваться языками разметки, поскольку автоматически расставляют теги и порождают только хорошо оформленные (или даже валидные) [5] входные документы, которые сразу без ошибок можно преобразовывать в выходные. Обратная сторона состоит в том, что генерируемую ими разметку сложно контролировать, а делать это приходится, поскольку конверторы, осуществляющие преобразования, обрабатывают именно XML-файл, а не с изображение текста, которое видит автор. Результат обработки зависит от того, какие в каждом конкретном случае поставлены теги, какие значения атрибутов присвоены узлам документа, и т. п. Наконец, работу опытного автора они скорее замедляют, чем ускоряют.

XML-редакторы, упрощающие набор разметки, интерфейсом напоминают обычные текстовые, но учитывают структуру набираемого документа, заданную элементами (рис. 2, 3).

 

Рисунок 2 — Редактор <oXygen/>

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

 

Рисунок 3 — XML-редактор Syntext Serna

 

XSLT-процессоры и XSLT-стили

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

Один из основных механизмов обработки XML-данных основан на языке XSL Transformations [4, 11, 12]. Его синтаксис базируется на XML, однако, назвать его языком разметки было бы неправильно из-за принципиально иной семантики. XSLT — декларативный язык, приспособленный для записи правил преобразования XML-документов [4, 11, 12]. Правила могут быть как совсем простыми, так и сложными, многоступенчатыми, с параметрами, ветвлениями и обращениями, в частности, рекурсивными, к другим правилам. Набор правил для решения некоторой прикладной задачи (фактически, программа на языке XSLT), называется XSLT-стилем. Программа, интерпретирующая XSLT-стили, называется XSLT-процессором. Входными данными для XSLT-процессора служат XML-файл и XSLT-стиль, на выходе формируются результаты выполненного преобразования.

Важнейшее преимущество XSLT в том, что c разработчика стилей снимается обязанность решать по-настоящему сложные программистские задачи вроде синтаксического разбора XML-кода и анализа структуры XML-документа. Создание прямого конвертора, допустим, из RTF в TeX, даже у квалифицированного программиста отняло бы гораздо больше времени, чем составление стиля для работы с XML-форматами сопоставимых описательных возможностей.

В настоящее время существует много бесплатных XSLT-процессоров, например, xsltproc.

Стандартные стили DocBook XSL

Требования к оформлению выходных документов в разных проектах существенно различны, поэтому попытки выпустить исчерпывающий набор XSLT-стилей обречены на провал. Создавать XSLT-стили заново в каждом проекте тоже нельзя, потому что сроки и стоимость этой работы получатся неприемлемыми. На практике обычно применяется свободно распространяемый комплект стандартных стилей DocBook XSL [2, 3]. Он поддерживает основные элементы макетов и целевые форматы, а также хорошо приспособлен к доработке для нужд конкретного проекта. Благодаря архитектуре XSLT адаптация стандартных стилей не требует модификации их кода. Новые правила, располагаемые в отдельных файлах, дополняют или замещают стандартные. Выполненные доработки не привязаны к конкретной копии стандартных стилей, следовательно:

• доработки не конфликтуют друг с другом, и ими легко обмениваться;

• возможность обновления версий DocBook XSL ограничена только их обратной совместимостью.

Типовые преобразования

Рассмотрим преобразования входных документов формата DocBook/XML в целевые форматы HTML, CHM и PDF. Соответствующие типовые цепочки схематически показаны на рис. 4.

 

Рисунок 4 — Преобразования DocBook/XML в HTML, CHM и PDF

Порядок формирования HTML-файлов:

1. С помощью XSLT-преобразования по входному документу формируется один HTML-файл или каталог взаимосвязанных HTML-файлов.

Порядок формирования хелп-файлов формата CHM:

1. С помощью XSLT-преобразования по входному документу формируется проект хелп-файла. Его состав и форматы входящих в него файлов диктуются требованиями инструментария HTML Help Workshop, стандартного для среды Microsoft Windows.

2. Проект обрабатывается компилятором hhc.exe, который входит в HTML Help Workshop. В результате формируется CHM-файл.

Порядок формирования файлов формата PDF:

1. С помощью XSLT-преобразования по входному документу формируется файл формата XSL-FO [14]. Он представляет собой XML-разметку текста, оформленного для вывода на печать, но не разбитого на страницы.

2. Файл формата XSL-FO обрабатывается программой FO-процессором, например, RenderX XEP. В результате формируется PDF-файл.

FO-процессором могут формироваться не только PDF-файлы, но и файлы в формате PostScript. Существуют FO-процессоры, предназначенные для формирования RTF-файлов.

Возможности публикации входных документов формата DocBook/XML не исчерпываются тремя перечисленными вариантами. Существуют XSLT-стили, поддерживающие форматы XHTML, Unix man pages, JavaHelp, TeX. Нет принципиальных препятствий к разработке стилей для формирования документов любого формата, во всяком случае, если его спецификация опубликована. [2, 3]

 

DITA

История развития и современное состояние. Краткий обзор

 

Название DITA представляет собой акроним полного названия этой технологии: Darwin Information Typing Architecture. Технология была разработана в корпорации IBM в 1999-2000 г., объявлено о ней было в 2001 г. В 2005 г. консорциум OASIS выпустил первый официальный релиз DITA. В настоящее время технология развивается силами OASIS DITA Technical Committee и IBM. Технология DITA применяется для разработки технической документации в ряде крупных корпораций, в том числе, IBM, Adobe, Nokia. Во многих средствах разработки технической документации и XML-редакторах имеется встроенная поддержка языка разметки DITA.

Что общего между DITA и другими технологиями?

 

В первом приближении технология DITA не многим отличается от любой другой технологии, построенной на основе языка разметки, будь то DocBook или, скажем, TeX.

Общая схема создания документа такова:

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

2. К полученному на первом этапе текстовому файлу применяется программа-конвертор. На выходе получается документ в том или ином формате, например, PDF или HTML. Оформление текста в этом документе определяется стилями, которые были подготовлены заранее самим автором или кем-то другим.

В чем тут выигрыш? Как минимум, в том, что мы перекладываем работу по оформлению документов на программу. Если мы должны поддерживать только один формат, то экономия не так уж велика (разметку-то делать все равно приходится), но если один и тот же текст необходимо представить в виде печатного руководства и в виде электронной справки, она уже очень ощутима.

Есть еще одна зона экономии. Представьте себе, что над одним документом или над одним комплектом документации трудится несколько авторов. Даже при условии их высокой дисциплинированности в оформлении разделов или документов, написанных разными авторами, скорее всего, будет разнобой. Это будет вызвано различными случайностями, что называется, ‘человеческим фактором’: Вася оформлял термины курсивом, а Петя почему-то подчеркиванием. Функциональная разметка к забывчивости такого рода намного более устойчива, потому что термины от элементов интерфейса и обозначения клавиш отличает любой здравомыслящий автор, поскольку здесь есть качественная разница, тогда как разница между разными шрифтовыми выделениями условна.

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

И TeX, и DocBook, и DITA это могут. В чем же особенность последней?

Чем DITA принципиально отличается от других технологий?

 

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

Технические решения, которые нам приходится документировать, во всяком случае, начиная с некоторого уровня их сложности, как правило, состоят из наборов однотипных компонент. Компоненты одного типа должны быть описаны по единому плану.

Предположим, некая среда разработки приложений включает в себя глобальные переменные, встроенные функции и объекты, классы. В таком случае все, например, классы должны быть описаны по одному и тому же плану. Если один автор, документируя класс, будет описывать сначала свойства, а потом методы, а другой, наоборот, сначала методы, а потом свойства, пользоваться такой документацией программисту будет, как минимум, неудобно. Хуже того, если один автор будет описывать связанные с этими классами исключительные ситуации (exceptions), а второй будет в принципе забывать это делать, то работа программиста с этими классами будет сильно осложнена. Каждая функция тоже должна быть описана по унифицированному плану, но для функций этот план, конечно, не такой, как для классов.

Более «гуманитарный» пример: финансовое приложение с большим количеством сложных экранных форм и не менее сложных отчетов. Для каждой формы необходимо указать назначение, состав полей, какие поля обязательны для заполнения, описать результаты сохранения введенных в форму данных, возможные проблемы при заполнении и т.д. Про каждый отчет необходимо сказать, как его сформировать, какие данные для этого обязательно должны присутствовать в базе данных, как настроить оформление отчета, как вывести отчет на печать, в какие каких форматах можно записать его на диск.

В общем, при описании однотипных предметов мы должны:

• придерживаться определенной последовательности изложения материала;

• не забыть сказать о критически важном (своего рода обязательные поля в документации).

Когда мы используем TeX или DocBook (а также Microsoft Word, AuthorIT, H&M и многое другое) мы можем в этом отношении только полагаться на дисциплину авторов и настырность их начальника. Технология DITA позволяет поддерживать унификацию текста на этом уровне технически, принуждая авторов соблюдать заданный начальником план. В этом и состоит ее принципиальное отличие от других технологий.

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

О типизации топиков в DITA можно сказать еще кое-что, но мы пока на этом остановимся и посмотрим, как технически обеспечивается соблюдение авторами ‘законов жанра’ в зависимости от типа топика.

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

Типы топиков. Специализация типов

Техническая возможность унификации описаний обеспечивается следующими мерами:

• каждый тип («жанр») топиков описан в DTD;

• все участвующие в проекте авторы имеют доступ к этим DTD;

• все участвующие в проекте авторы пользуются XML-редакторами для ввода текста.

Изначально в DITA описаны четыре типа топиков:

• topic — фрагмент произвольного назначения;

• concept — концепция или, иначе говоря, информация общего назначения;

• task — последовательность действий, предназначенных для решения какой-либо задачи;

• reference — справочная информация.

В случае необходимости вы можете описать в виде DTD собственные типы топиков, например, form для документирования экранных форм и report для отчетов. Процедура создания собственных типов топиков называется специализацией, а сами новые типы топиков — специализированными типами.

И тут снова возникает вопрос: для чего нам нужна какая-то особая технология, если мы сами можем написать любое DTD и писать по нему текст? Конечно, мы это можем. Однако не будем забывать, что текст необходимо не только набирать, но и оформлять. Поэтому для каждого придуманного нами типа топика мы должны будем еще разработать стиль оформления, в котором для каждого элемента задан способ обработки. Под обработкой здесь понимается и визуальное оформление (заголовки крупным шрифтом, термины курсивом), но и логика компиляции документов, например, формирование оглавления или разбивка документа на HTML-страницы, каждая из которых соответствует разделу определенного уровня.

В комплекте инструментария DITA уже есть готовые стили, реализующие все наиболее важные функции формирования документов примерно на том же уровне, на котором это делают стили DocBook XSL. Технология DITA позволяет, с одной стороны, создавать новые типы топиков, а с другой, использовать для их обработки уже имеющиеся стили. Это достигается благодаря приему, который в объектно-ориентированном программировании известен как наследование.

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

В листингах 1, 2 «Приложения Б» приведены примеры топиков типа concept и task.

Рассмотрим такой пример. Тип (и, соответственно, элемент) concept в числе прочего содержимого имеет подчиненный элемент title, предназначенный, как вы наверно догадались, для разметки заголовка топика. Допустим, на основе типа concept мы решили создать новый тип screen-form. Мы хотим, чтобы у него тоже был заголовок, однако, указывать это явно в описании типа screen-form мы не обязаны. Заголовком новый тип будет обладать, поскольку таковой имеется у базового типа.

Напомним, что речь только что шла не о конкретных топиках, а о типах топиков. Что же касается самих топиков, то с ними будет происходить следующее:

• При создании в XML-редакторе нового топика типа screen-form в него автоматически будет вставляться обязательный элемент title.

• При сборке документа заголовки топиков типа screen-form будут правильно оформлены и включены в оглавление.

Специализация не подразумевает обязательного сохранения имен наследуемых элементов. Мы можем принять решение о том, что в топиках типа screen-form заголовок размечается элементом под названием caption, а не title. Тогда при создании типа screen-form мы указываем, что внутри элемента screen-form должен присутствовать ровно один элемент caption, и что он соответствует элементу title базового типа.

Технически специализация типа заключается в написании DTD, ссылающегося на DTD базового типа. Делать это надо по определенным правилам, которые описаны в документации DITA, и пересказывать которые мы здесь не будем.

Специализация допускается для любого типа топиков, а не только для базовых, т.е. в сложных проектах типы топиков могут образовывать довольно «ветвистое» дерево. Таким образом, язык разметки DITA в отличие от языка разметки DocBook/XML предполагает расширение для нужд конкретного проекта.

Словари

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

Архитектура документа в DITA

 

Когда мы набираем документ в обычном текстовом процессоре (для простоты будем говорить о Microsoft Word) текст как таковой и его оформление слиты в одном файле. Что в этом плохого, давно известно: такой документ сложно (читай, дорого) сопровождать.

Технология DocBook проводит четкую, насколько это возможно, границу между текстом и оформлением: текст хранится в XML-файлах, оформление задано XSLT-стилями. В остальном докбуковский документ, если прибегать специальным трюкам, устроен примерно так же, как вордовский. Он делится по иерархическому принципу на структурные элементы (главы, разделы подразделы и т.д.), а в самом низу этой иерархии находится т.н. сплошной текст. Правда, за счет тегового синтаксиса в DocBook иерархия обозначена более четко, чем в большинстве текстовых процессоров.

В докбуковском документе, как и в вордовском, автор с самого начала придает тексту определенную структуру. Что в этом плохого? При создании крупных комплектов документации фрагменты, повторяющиеся в разных документах, приходится размножать методом ‘copy-paste’, что не только трудоемко само по себе, но опять-таки усложняет сопровождение, поскольку при внесении в документацию изменений приходится тщательно отслеживать все копии исправленного фрагмента.

И DocBook, и Microsoft Word, и TeX, и FrameMaker позволяют выносить повторяющиеся фрагменты в отдельные файлы. Верно, но DITA закрепляет разделение текста и структуры на уровне идеологии. При использовании DITA вы обязательно будете хранить сплошной текст в виде фрагментов, называемых топиками, а структуру каждого документа описывать в отдельном файле, который называется картой.

Карта документа представляет собой формализованное описание его структуры. Она похожа на оглавление, только для каждого структурного элемента в ней дается не номер страницы включающая ссылка на некоторый топик. Таким образом, любой фрагмент сплошного текста, вы можете поместить в любой документ на любой уровень. При этом DITA предлагает собственные языковые средства, хорошо приспособленные для описания топиков, структур и включающих ссылок. Пример карты см. в листинге 3 «Приложения Б».

Технически карта реализуется в виде отдельного XML-документа, созданного с использованием языка разметки DITA. На листинге 6 показан пример карты. предполагается, что каждый топик в соответствии с рекомендацией разработчиков технологии DITA находится в отдельном файле.

Формирование документов. DITA Open Toolkit

Исходный документ

 

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

Технически все файлы топиков и все карты мы можем поместить в один каталог. На практике в хоть сколько-нибудь сложных проектах топики распределяют по некоторому дереву каталогов в соответствии с их содержанием.

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

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

Инструментарий

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

Для формирования документов требуется следующее программное обеспечение:

• комплект программ и XSLT-стилей и документации DITA Open Toolkit;

• SUN Java Developer Kit версии не ниже 1.4.2;

• Microsoft HTML Help Workshop (для формирование CHM-файлов);

• RenderX XEP (для формирования качественных PDF-документов).

Кроме RenderX XEP весь инструментарий бесплатный.

В состав DITA Open Toolkit входят следующие компоненты:

• DTD языка разметки DITA;

• XSLT-стили для обработки дитовских документов;

• FO-процессор FOP (предназначен для формирования PDF);

• среда для управления обработкой ANT;

• документация и примеры.

Порядок формирования документа

Для каждого документа необходимо сформировать следующие файлы:

• Конфигурационный файл, содержащий параметры, управляющие формированием документа. К таковым относятся, в частности, имя файла карты, расположение и имя конечного документа, формат конечного документа.

• Командный файл, непосредственно выполняющий формирование документа. Этот файл, как правило, состоит из одной строки: вызова исполняемого файла ant с указанием имени конфигурационного файла в качестве параметра.

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

Для формирования документа достаточно запустить командный файл.

Примеры конфигурационных и командных файлов входят в состав DITA Open Toolkit.

 

Применение систем управления версиями

 

Система управления версиями (от англ. Version Control System, VCS или Revision Control System) — программное обеспечение для облегчения работы с изменяющейся информацией. Система управления версиями позволяет хранить несколько версий одного и того же документа, при необходимости, возвращаться к более ранним версиям, определять, кто и когда сделал то или иное изменение и многое другое.

Такие системы наиболее широко применяются при разработке программного обеспечения, для хранения исходных кодов разрабатываемой программы. Однако, они могут с успехом применяться и в других областях, в которых ведётся работа с большим количеством непрерывно изменяющихся электронных документов, в частности, они всё чаще применяются в САПР, обычно, в составе систем управления данными об изделии (PDM). Управление версиями используется в инструментах конфигурационного управления (Software Configuration Management Tools).

 

Централизованные системы управления версиями

 

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

Большинство систем управления версиями используют централизованную модель, когда имеется единое хранилище документов, управляемое специальным сервером, который и выполняет бо́льшую часть функций по управлению версиями (см. рис. 5). Пользователь, работающий с документами, должен сначала получить нужную ему версию документа из хранилища; обычно создаётся локальная копия документа, т. н. «рабочая копия». Может быть получена последняя версия или любая из предыдущих, которая может быть выбрана по номеру версии или дате создания, иногда и по другим признакам. После того, как в документ внесены нужные изменения, новая версия помещается в хранилище. В отличие от простого сохранения файла, предыдущая версия не стирается, а тоже остаётся в хранилище и может быть оттуда получена в любое время. Сервер может использовать т. н. дельта-компрессию — такой способ хранения документов, при котором сохраняются только изменения между последовательными версиями, что позволяет уменьшить объём хранимых данных.

 

Рисунок 5 — Централизованная модель управления версиями

 

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

Часто бывает, что над одним проектом одновременно работают несколько человек. Если два человека изменяют один и тот же файл, то один из них может случайно отменить изменения, сделанные другим. Системы управления версиями отслеживают такие конфликты и предлагают средства их решения. Большинство систем может автоматически объединить (слить) изменения, сделанные разными разработчиками. Однако такое автоматическое объединение изменений, обычно, возможно только для текстовых файлов и при условии, что изменялись разные (непересекающиеся) части этого файла. Такое ограничение связано с тем, что большинство систем управления версиями ориентированы на поддержку процесса разработки программного обеспечения, а исходные коды программ хранятся в текстовых файлах. Если автоматическое объединение выполнить не удалось, система может предложить решить проблему вручную.

Часто выполнить слияние невозможно ни в автоматическом, ни в ручном режиме, например, если формат файла слишком сложен или, вообще, неизвестен. Некоторые системы управления версиями дают возможность заблокировать файл в хранилище. Блокировка не позволяет другим пользователям получить рабочую копию или препятствует изменению рабочей копии файла (например, средствами файловой системы) и обеспечивает, таким образом, исключительный доступ только тому пользователю, который работает с документом.

Многие системы управления версиями предоставляют ряд других возможностей:

• Позволяют создавать разные варианты одного документа, т. н. ветки, с общей историей изменений до точки ветвления и с разными — после неё.

• Дают возможность узнать, кто и когда добавил или изменил конкретный набор строк в файле.

• Ведут журнал изменений, в который пользователи могут записывать пояснения о том, что и почему они изменили в данной версии.

• Контролируют права доступа пользователей, разрешая или запрещая чтение или изменение данных, в зависимости от того, кто запрашивает это действие.

 

CVS, Subversion

CVS

Concurrent Versions System (CVS) — одна из наиболее распространенных сегодня SCM. Она имеет централизованную архитектуру с моделью «набора изменений», в которой разработчики работают с центральным репозиторием при совместной разработке программного обеспечения. CVS используется повсеместно и она доступна как стандартная часть любого дистрибутива Linux. Благодаря своему простому и удобному (для многих из нас) синтаксису, она является популярным выбором как при одиночной, так и командной разработке.

 

Листинг 1 демонстрирует набор простых CVS команд с кратким описанием каждой. Для более подробной информации, обратитесь к секции Ресурсы .

 

Листинг 1 — Примеры команд для CVS

 

 

# Создать новый репозиторий

cvs -d /home/user/new_repository init

 

# Подсоединиться к корневому репозиторию

export CVSROOT=:pserver:user@example.com:/cvs_root

 

# Выгрузить блок для модуля из корневого репозитория

cvs checkout project

 

# Обновить локальный блок из корневого репозитория

cvs update

 

# Внести изменения из локального блока в коневой репозиторий

cvs commit

 

# Добавить новые файлы в локальный блок

cvs add <file/subdirectory>

 

# Показать изменения, сделанные в локальном блоке

cvs diff

 

Для CVS есть большое количество графических интерфейсов с открытым кодом, которые вы можете использовать, например, WinCVS и TortoiseCVS (которая интегрируется с Microsoft Windows Explorer, если вам это удобно).

 

Несмотря на повсеместное использование, CVS имеет свои недостатки. CVS не позволяет переименовывать файлы, также она имеет недостатки при работе с определенными файлами, например, с символьными ссылками. Изменения, отслеживаемые самим файлом, могут иногда надоедать. Синхронизация может быть иногда проблематична (CVS внутри использует diff3 для этой цели).

 

Однако, CVS полезен, если действительно это необходимо сделать, и он пригоден для всех главных платформ. Если вам нравится CVS, в целом, то Subversion может быть для вас как раз тем, что вы ищете.

 

Subversion

 

Subversion (SVN) была разработана как прямая замена CVS, но без свойственных CVS заранее определенных выпусков. Как и CVS, Subversion — централизованное решение и использование модели «моментального снимка». Ее команды, похожие на те же команды CVS, но с новыми дополнениями, хорошо управляются с такими вещами, как удаление файлов, перенаименование файлов или возврат к оригинальному файлу.

 

Subversion также позволяет удаленный доступ посредством большого количества протоколов, таких как протокол HTTP, протокол безопасности HTTP, или протокол, выполненный по заказу SVN, который также поддерживает туннелирование через Оболочку Безопасности [SSH].

 

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

 

Листинг 2 — Примеры команд для Subversion

 

 

# Создать новый репозиторий

svnadmin create /home/user/new_repository

 

# Выгрузить блок из корневого репозитория

svn checkout file:///server/svn/existing_repository new_repository

 

# Обновить локальный блок из корневого репозитория.

svn update

 

# Внести изменения из локального блока в корневой репозиторий.

svn commit

 

# Добавить новые файлы в локальный блок

svn add <file/subdirectory>

 

# Показать изменения, сделанные в локальном блоке

svn diff

 

#Переименовать файл в локальном блоке

svn rename <old_file> <new_file>

 

# Удалить файлы

svn delete <file/subdirectory>

 

Следуя традициям CVS, Subversion использует в работе графический внешний интерфейс, такой как ViewCVS and TortoiseSVN. Существуют также средства конвертировать репозиторий CVS в Subversion (такие как cvs2svn.py), но они, как сообщают, управляются не со всем набором ответвлений и сопровождений данных тегами в случаях сложных репозиториев. Учитывая все Open Source проекты, со временем ситуация улучшится. Subversion также использует в работе TortoiseMerge в качестве различия между средствами отображения и исправления.

 

В Subversion фиксированое число выпусков, испытанных CVS пользователями, такие как организация разработки новых поколений определенных файлов, мелких действий и отладок. Если вам нравится CVS и вам нравится подход центрального репозитория, то Subversion — это SCM для вас.

 

Теперь давайте оттолкнемся от централизованного подхода и рассмотрим децентрализованные системы управления версиями.

 

Децентрализованные системы управления версиями

 

В случае с распределенной VCS (см. рис. 6), каждый разработчик имеет полную копию репозитория и работает с ним, время от времени синхронизируясь с репозиториями остальных. Таким образом, для организации целенаправленной разработки потребуются какие-то не технические, а организационно-административные средства. Зато получаем множество преимуществ:

 

• Раз у каждого есть полная копия репозитория, работа всех разработчиков пропасть не может вообще.

• Часто выполняемые операции — прежде всего, commit — происходят почти мгновенно, т.к. не требуют соединения по сети.

• Каждый разработчик может создавать в своем репозитории ветки для каких-то экспериментов, всем остальным даже не нужно знать об этом.

• Т.к. в распределенных VCS предполагается регулярная синхронизация репозиториев, в них гораздо более эффективно реализована операция слияния веток (здесь это одна из базовых операций, в отличие от централизованных VCS, где это делается нечасто).

• Каждый разработчик может взять («утянуть») у другого один или не-сколько коммитов, применив их к своему коду.

 

 

Рисунок 6 — Децентрализованная (распределённая) модель управления версиями

 

Git

Git — распределённая система управления версиями файлов. Проект был создан Линусом Торвальдсом для управления разработкой ядра Linux. На сегодняшний день поддерживается Джунио Хамано (англ. Junio C. Hamano) [17].

Примерами проектов, использующих Git, являются Linux kernel, Cairo, GNU Core Utilities, Mesa, Wine, Chromium, Compiz Fusion и некоторые дистрибутивы GNU/Linux.

Программа является свободной и выпущена под лицензией GNU GPL версии 2.

Система спроектирована как набор программ, специально разработанных с учётом их использования в скриптах. Это позволяет удобно создавать специализированные системы контроля версий на базе Git или пользовательские интерфейсы. Например, Cogito является именно таким примером фронтенда к репозиториям Git, а StGit использует Git для управления коллекцией патчей.

Git поддерживает быстрое разделение и слияние версий, включает инструменты для визуализации и навигации по нелинейной истории разработки. Как и Darcs, BitKeeper, Mercurial, SVK, Bazaar и Monotone, Git предоставляет каждому разработчику локальную копию всей истории разработки, изменения копируются из одного репозитория в другой.

Удалённый доступ к репозиториям Git обеспечивается git-daemon, SSH- или HTTP-сервером. TCP-сервис git-daemon входит в дистрибутив Git и является наряду с SSH наиболее распространённым и надёжным методом доступа. Метод доступа по HTTP, несмотря на ряд ограничений, очень популярен в контролируемых сетях, потому что позволяет использование существующих конфигураций сетевых фильтров.

 

Mercurial

Mercurial — кроссплатформенная распределённая система управления версиями, разработанная для эффективной работы с очень большими репозиториями кода. Mercurial первоначально был написан для Linux, позже портирован под Windows, Mac OS X и большинство Unix-систем. В первую очередь он является консольной программой. Все его операции запускаются параметрами программы hg, название которой взято от обозначения химического знака ртути (англ. mercury).

Система Mercurial написана на Python, хотя чувствительные к производительности части (например, своя реализация diff) выполнены в качестве Python-расширений на C. Репозитории Mercurial управляются при помощи утилиты командной строки hg.

Наряду с традиционными возможностями систем контроля версий, Mercurial поддерживает полностью децентрализованную работу (отсутствует понятие основного хранилища кода), ветвление (возможно вести несколько веток одного проекта и копировать изменения между ветками), слияние репозиториев (чем и достигается «распределённость» работы). Поддерживается обмен данными между репозиториями через HTTP/HTTPS, SSH [18] и вручную при помощи упакованных наборов изменений.

Mercurial использует SHA1-хеши для идентификации ревизий и позволяет присваивать отдельным ревизиям индивидуальные метки.

Утилита hg обладает компактным интерфейсом, и Mercurial считается более простой в освоении системой, чем, например, git. [18]

В комплекте с Mercurial поставляются CGI-сценарии для предоставления веб-интерфейса к репозиториям [18].

 

Есть графическая оболочка TortoiseHg [18], работающая как под Windows (с интеграцией в Explorer), так и под Linux (в виде отдельного приложения или с интеграцией в Gnome/Nautilus).

Ряд сред разработки имеет возможности для работы с Mercurial, например Microsoft Visual Studio, IntelliJ IDEA, Eclipse, PIDA, NetBeans. Возможна работа с Mercurial из Emacs c помощью входящего в Emacs универсального пакета VC.

Экспериментальная поддержка Mercurial есть в системе Trac.

При помощи утилиты Tailor или расширения convert поддерживается конвертирование репозиториев других систем контроля версий, включая CVS, Subversion, Git, Darcs, GNU Arch, Bazaar.

 

Организационно-экономический раздел

В организационно-экономическом разделе дипломного проекта отражена цена разработки с учетом налога на добавленную стоимость.

Расчет структуры цены проводится методом прямого калькулирования с учетом законодательных актов в части ценообразования по состоянию на 15 апреля 2010 года.

Расчет проектно-конструкторских затрат

Материалы и ПКИ

 

Затраты по статье «Материалы и ПКИ» рассчитаны исходя из потребностей на сырье и материалы, покупные изделия и полуфабрикаты, вспомогательные материалы, комплектующие изделия, пакеты прикладных программ, дискеты, ватман и др. по цене приобретения без НДС.

Расчет затрат на материалы и ПКИ приведен в таблице 1.

 

Таблица 1 – Расчет затрат на материалы и ПКИ

Наименование Единица Коли- Цена едини-цы, Сумма, Обосно-

материалов, ПКИ изме- чест- руб. руб. вание

и других

материальных ресурсов рения во (без НДС)

1 2 3 4 5 6

 

Флэш шт. 1 550 550

прайс ─

листы

Всего 550

Расходы на оплату труда

Расходы на оплату труда определены исходя из среднемесячного размера расходов на оплату труда одного работника и трудоемкости работ. С учетом премии и территориального коэффициента среднемесячный размер расходов на оплату труда одного работника составит 18 000 рублей.

Продолжительность и трудоемкость проводимых работ определяется в соответствии с календарным планом, приведенном в таблице 2.

Таблица 2 – Календарный план проведения работ

№ Срок выполнения Трудо-ёмкость (чел/час)

пп Наименование работ начало окончание

1. Получение и анализ задания на раз-работку 01.02.2010 07.02.2010 24

2. Подбор, изучение научно-технической литературы, подготовка материалов и справочных данных 08.02.2010 16.02.2010 105

3. Компоновка и оформление собран-ных данных 17.02.2010 01.03.2010 90

4. Изучение программных средств, ис-пользуемых для разработки доку-ментации 02.03.2010 18.03.2010 120

5. Разработка документации с помощью различного ПО 19.03.2010 31.03.2010 50

6. Сравнение эффективности разработ-ки документации с использованием различного ПО 01.04.2010 18.04.2010 66

7. Выпуск готовой документации для всех целевых платформ 19.04.2010 03.05.2010 58

8. Технико-экономическое обоснование стоимости разработки 04.05.2010 06.05.2010 16

9. Обоснование раздела «БЖД» 07.05.2010 12.05.2010 22

10. Анализ разработки, выводы и оформление проекта 13.05.2010 30.05.2010 60

ИТОГО: 631

 

При среднем количестве часов в месяц в 2010 году — 165,6 часов в месяц продолжительность работ в месяцах будет составлять 3,8 месяца (631/165,6).

Полные расходы на оплату труда приведены в таблице 3

Таблица 3. Расчет расходов на оплату труда

№ Сроки Категория работающих

этапа ИТР и служащие

работ Начало Окон- Продол Кол-во Трудо-ем- Среднемесяч-ный Расходы

по чание житель участ- кость размер расхо-дов на

теме ность ников (чел/мес) на оплату тру-да оплату

(мес.) (чел.) одного челове-ка труда

в месяц

1 2 3 4 5 6 7 8

1 01.02.10 30.05.10 3,8 1 3,8 18 000,00 68 400

Отчисления на социальные нужды

В соответствии с Налоговым кодексом РФ (часть вторая) установлен единый социальный налог по ставке 26% от расходов на оплату труда.

Кроме того, предприятие производит отчисления на обязательное социальное страхование от несчастных случаев на производстве и профессиональных заболеваний в размере 0,2%.

Таким образом, суммарный тариф отчислений на социальные нужды составит 26,0% + 0,2 % = 26,2% от суммы расходов на оплату труда.

Размер отчислений на социальные нужды составит:

68 400 * 0,262 = 17 920,8 рублей

 

Командировочные расходы

В нашем случае затраты отсутствуют.

 

Накладные расходы

Сюда относятся:

• расходы на содержание аппарата работников управления;

• содержание зданий, сооружений, инвентаря общехозяйственного назначения;

• конторские и телефонные расходы;

• плата (или содержание) за пожарную и сторожевую охрану;

• плата за аренду;

• оплата услуг связи, вычислительных центров, банков;

• оплата работ по сертификации продукции;

• затраты на обеспечение нормальных условий труда и техники безопасности.

Накладные расходы определяются индивидуально по каждому предпри-ятию и зависят от вида деятельности и составляют 40% от расходов на оплату труда.

 

Накладные расходы = 68 400 * 0,4 = 27 360 рублей

 

Затраты по работам, выполняемым сторонними организациями и предприятиями

Затраты сторонних организаций обосновываются расчетом договорных цен выполняемых ими работ и сопровождаются процессом согласования с учетом их отраслевых особенностей.

В нашем случае затраты отсутствуют.

 

Структура цены

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

Плановая прибыль определяется в размере 18% от себестоимости собственных работ.

 

Плановая структура цены представлена в таблице 4.

 

Таблица 4. Плановая структура цены

(руб.)

№ Наименование статей затрат Всего Доля в полной себестоимости в %

п/п

1 Материалы и ПКИ 550,00 0,40

2 Расходы на оплату труда 68 400,00 59,87

3 Отчисления на социальные нуж-ды(26%+0,2%=26,2%) от расходов на оплату труда 17 920,80 15,68

4 Прочие прямые расходы (расходы на служеб-ные командировки) 0,00 0,00

5 Накладные расходы (40% от расходов на оплату труда) 27 360,00 23,95

Итого себестоимость собственных работ 114 230,00

6 Затраты по работам, выполняемым сторонними организациями и предприятиями 0,00 0,00

Итого полная себестоимость 114 230,00 100,00

7 Прибыль 18% от себестоимости собственных работ 20 561,40

8 Цена 134 791,40

9 НДС 18% 24 262,45

10 Цена реализации (Цена + НДС) 159 053,85

 

Затраты на проектно-конструкторские работы составили 159 053,85 рублей.

 

Расчет ожидаемого годового экономического эффекта от применения ме-тодики эффективной разработки программной документации с использованием систем управления версиями и XML-технологий

 

Ожидаемый годовой экономический эффект образуется за счёт фактора снижения трудоёмкости проводимых работ и, как следствие, сокращение количества работников, занятых разработкой технической документации и определяется по формуле:

Э = ∆N * ФЗП * 12 мес. — Кпр.

Где:

∆N — кол-во работников, планируемых к увольнению после вне-дрения разработки соответственно (чел.),

ФЗП — среднемесячный фонд заработной платы с учётом отчислений на соц. страхование одного работника (руб. в месяц), 18 000 руб. * 1.262

12 мес. — число месяцев в году;

Кпр. — затраты на проектно-конструкторские работы (руб.)

 

Э = 2 * 22 716 * 12 — 159 053,85 = 386130,15 (руб.)

 

Ожидаемый годовой экономический эффект за счёт снижения трудоёмкости проводимых работ составит 386 130,15 рублей.

 

Безопасность жизнедеятельности

Помещения для эксплуатации ПЭВМ

 

Помещения для эксплуатации ПЭВМ должны иметь естественное и ис-кусственное освещение. Эксплуатация ПЭВМ в помещениях без естественного освещения допускается только при соответствующем обосновании и наличии положительного санитарно-эпидемиологического заключения, выданного в установленном порядке.

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

Для внутренней отделки интерьера помещений, где расположены ПЭВМ, должны использоваться диффузно-отражающие материалы с коэффициентом отражения для потолка — 0,7 — 0,8; для стен — 0,5 — 0,6; для пола — 0,3 -0,5.

Помещения, где размещаются рабочие места с ПЭВМ, должны быть оборудованы защитным заземлением (занулением) в соответствии с техническими требованиями по эксплуатации.

 

Микроклимат на рабочем месте

 

Работа оператора по виду трудовой деятельности относится к группе B – творческая работа в режиме диалога с ЭВМ, по напряжённости ко II категории сложности.

В производственных помещениях, в которых работа на ВДТ и ПЭВМ является основной (диспетчерские, операторские, расчетные, кабины и посты управления, залы вычислительной техники и др.), должны обеспечиваться оптимальные параметры микроклимата.

В помещениях, оборудованных ПЭВМ, должна проводится ежедневная влажная уборка и систематическое проветривание после каждого часа работы на ПЭВМ.

Для повышения влажности воздуха в помещениях с ВДТ и ПЭВМ следует применять увлажнители воздуха, заправляемые ежедневно дистиллированной или прокипяченной питьевой водой.

Содержание вредных химических веществ в воздухе производственных помещений, в которых работа на ВДТ и ПЭВМ является основной (диспетчерские, операторские, расчетные, кабины и посты управления, залы вычислительной техники и др.), и вспомогательной, не должно превышать ПДК, установленные ГОСТом 12.1.005-88 Предельно допустимых концентрации вредных веществ в воздухе рабочей зоны.

Рекомендации по климатическим условиям работы.

Таблица 1 – Оптимальные нормы микроклимата для помещений с ВДТ и ПЭВМ

Период года Категория работ Температура воздуха C не более Относит. влажность воздуха, % Скорость движения воздуха, м/с

Холодный легкая – 1а 22 – 24 40 – 60 0,1

Теплый легкая – 1а 23 – 25 40 – 60 0,1

 

К категории 1а относятся работы, производимые сидя и не требующие физического напряжения, при которых расход энергии составляет до 120 ккал/ч.

 

Освещение помещений и рабочих мест с ВДТ и ПЭВМ

 

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

Рабочие столы следует размещать таким образом, чтобы видеодисплей-ные терминалы были ориентированы боковой стороной к световым проемам, чтобы естественный свет падал преимущественно слева.

Освещенность на поверхности стола в зоне размещения рабочего доку-мента должна быть 300 — 500 люкс. Допускается установка светильников местного освеще¬ния для подсветки документов. Местное освещение не должно создавать бликов на поверхности экрана и увеличивать освещенность экрана более 300 люкс. Следует ограничивать прямую блесткость от источников освещения, при этом яркость светящихся поверхностей (окна, светильники и др.), находящихся в поле зрения, должна быть не более 200 кд/м2, и отраженную блесткость на рабочих поверхностях (экран, стол, клавиатура и др.) за счет правильного выбора типов светильников и расположения рабочих мест по отношению к источникам естественного и искусственного освещения, при этом яркость бликов на экране ПЭВМ не должна превышать 40 кд/м2 и яркость потолка также не должна превышать 200 кд/м2.

В качестве источников света при искусственном освещении следует при-менять преимущественно люминесцентные лампы типа ЛБ и компактные лю-минесцентные лампы (КЛЛ). В светильниках местного освещения допускается применение ламп накаливания, в том числе галогенные. Яркость светильников общего освещения в зоне углов излучения от 50 до 90 градусов с вертикалью в продольной и поперечной плоскостях должна составлять не более 200 кд/м2, защитный угол светильников должен быть не менее 40 градусов.

Для освещения помещений с ПЭВМ следует применять светильники с зеркальными параболическими решетками, укомплектованными электронными пуско-регулирующими аппаратами (ЭПРА). Допускается использование многоламповых светильников с электромагнитными пуско-регулирующими аппаратами (ЭПРА), состоящими из равного числа опережающих и отстающих ветвей. Применение светильников без рассеивателей и экранирующих решеток не допускается.

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

Необходимо помнить, что для обеспечения нормируемых значений освещенности в помещениях для использования ПЭВМ следует проводить чистку стекол оконных рам и светильников не реже двух раз в год и проводить своевременную замену перегоревших ламп.

 

Рисунок 4.4.1 – Рабочий кабинет оператора с естественным и искусственным освещением.

 

Шум и вибрация

 

При выполнении основной работы на ВДТ и ПЭВМ (диспетчерские, операторские, расчетные кабины и посты управления, залы вычислительной техники и др.), в помещениях для размещения шумных агрегатов вычислительных машин (АЦПУ, принтеры и т.п.) уровень шума не должен превышать 75 дБА (ГОСТ 12.1.003.-83 Шум. Общие требования к безопасности). Такое оборудование должно размещаться вне помещений с ПЭВМ.

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

Снизить уровень шума в помещениях с ВДТ и ПЭВМ можно использованием звукопоглощающих для отделки помещений (разрешенных органами и учреждениями Госсанэпиднадзора России), подтвержденных специальными акустическими расчетами.

Дополнительным звукопоглощением служат однотонные занавеси из плотной ткани, гармонирующие с окраской стен и подвешенные в складку на расстоянии 15 — 20 см от ограждения.

 

Организация рабочих мест с ВДТ и ПЭВМ

 

Рабочее место должно соответствовать требованиям:

• ГОСТ 12.2.032-78 Рабочее место при выполнении работ сидя. Общие эргономические требования.

• ГОСТ 22269-76 Система «человек-машина». Рабочее место оператора. Взаимное расположение элементов рабочего места. Общие эргономические требования.

• ГОСТ 21829-76 Система «человек-машина». Кодирование зри-тельной информации. Общие эргономические требования.

• ГОСТ 12.1.030-81 Электробезопасность.

Рабочие места с ВДТ и ПЭВМ по отношению к световым проемам должны располагаться так, чтобы естественный свет падал сбоку, преимущественно слева.

Схемы размещения рабочих мест с ВДТ и ПЭВМ должны учитывать расстояния между рабочими столами с видеомониторами (в направлении тыла поверхности одного видеомонитора и экрана другого видеомонитора), которое должно быть не менее 2,0 м, а расстояние между боковыми поверхностями видеомониторов — не менее 1,2 м.

Конструкция рабочего стола должна обеспечивать оптимальное размещение на рабочей поверхности используемого оборудования с учетом его количества и конструктивных особенностей (размер ВДТ и ПЭВМ, клавиатуры и др.), характера выполняемой работы. Высота рабочей поверхности стола должна регулироваться от 680 до 800 мм, при отсутствии возможности регулировки высота должна составлять 725 мм. Рабочий стол должен иметь пространство для ног:

• ширина – 500 мм.

• Глубина на уровне колен не менее 450 мм.

• Глубина на уровне вытянутых ног не менее 650 мм.

Конструкция рабочего стула (кресла) должна обеспечивать поддержание рациональной рабочей позы при работе на ВДТ и ПЭВМ, позволять изменять позу с целью снижения статического напряжения мышц шейно — плечевой области и спины для предупреждения развития утомления.

Рабочий стул (кресло) должен быть подъемно-поворотным и регулируемым по высоте и углам наклона сиденья и спинки, а также — расстоянию спинки от переднего края сиденья, при этом регулировка каждого параметра должна быть независимой, легко осуществляемой и иметь надежную фиксацию:

• Ширина и глубина поверхности сидения не менее 400 мм.

• Поверхность сиденья с закруглённым передним краем.

• Регулировка высоты от 400 до 550 мм., угол наклона вперёд до 15°, назад до 5°.

• Высота опорной поверхности спинки 300±20мм., шимрина не менее 380 мм.

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

Экран видеомонитора должен находиться от глаз пользователя на оптимальном расстоянии 600 — 700 мм, но не ближе 500 мм с учетом размеров алфавитно — цифровых знаков и символов.

 

Пожарная безопасность

 

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

Согласно СанПиН 21-07-97 помещение относится ко II категории огне-стойкости. Для изготовления строительных конструкций использованы: кир-пич, железобетон, металл и другие негорючие материалы. Применение дерева ограничено. Категория пожаробезопасности – K1(малопожароопасное). Мебель, оргтехника – горючие вещества, сейфы и оборудование – трудносгораемые вещества, которые при взаимодействии с огнём могут гореть без взрыва.

Участок ПЭВМ по пожарной опасности относится к категории пожаро-опасных и характеризуется тем, что в помещении находятся несгораемые вещества и материалы в холодном состоянии.

Пожарная безопасность может быть обеспечена мерами пожарной про-филактики и активной пожарной защитой.

Необходимо предусмотреть безопасную эвакуацию людей на случай возникновения пожара. При пожаре люди должны покинуть помещение в течение минимального времени. В соответствии с СНиП 11-2-80 число эвакуационных выходов из зданий, помещений должно составлять не менее двух.

Исходя из норм пожарной безопасности, для машинного зала ВЦ требуются следующие первичные средства пожаротушения:

• один химпенный (ОХП-10) или воздушно-пенный огнетушитель (ОВП-5 или ОВП-10), с помощью которого можно тушить твердые материалы и горючие жидкости (кроме установок под напряжением);

• войлок, кошму или асбест (1Х1; 2Х1,5; 2X2 м).

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

 

Профилактика пожара

 

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

ГОСТ 12.1.004-91 «Пожарная безопасность. Общие требования» устанавливает общие требования к системам пожарной безопасности объектов различного назначения.

Одно из условий обеспечения пожаробезопасности – ликвидация воз-можных источников воспламенения.

В помещении источниками воспламенения могут быть:

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

• неисправные электроприборы. Необходимые меры для исключе-ния пожара включают в себя своевременный ремонт электроприборов, качественное исправление поломок, не использование неисправных электроприборов;

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

• короткое замыкание в электропроводке. В целях уменьшения ве-роятности возникновения пожара вследствие короткого замыкания необходимо, чтобы электропроводка была скрытой.

• Попадание в здание молнии. Во избежание этого рекомендуется установить на крыше здания молниеотвод.

• Несоблюдение мер пожарной безопасности и курение в помеще-нии также может привести к пожару. Для устранения возгорания в результате курения, разрешить курение в строго отведённом для этого месте.

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

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

 

Заключение

 

В данной дипломной работе были рассмотрены современные методы разработки документации (в частности, технической документации для программного обеспечения, разрабатываемого компанией «Системы Папилон».

Рассмотренные методы:

Применение XML-ориентированных языков логической разметки для создания различной по форме документации из «единого источника»

С учётом как текущих, так и возможных будущих требований:

• Разработка ведётся коллективно

• С полной поддержкой мультиязычности

• С результатом в виде файлов контекстной справки Microsoft Compiled HTML Help, GNU/Linux, PDF, доступными через Интернет и в отпечатанном виде.

позволяют эффективно и быстро решить поставленные перед документаторами задачи.

 

Для небольшого отдела (в частности, группой документирования отдела программирования компании «Системы Папилон»), рекомендуется вести разработку с использованием инструментов DocBook/XML по следующим причинам:

• В разработке задействованы относительно небольшие объёмы первичных документов

• DocBook/XML хорошо документирован на русском языке имеет устойчивое сообщество в России

• DocBook/XML несколько проще в освоении

 

В качестве системы управления версиями автор рекомендует централизованную систему управления версиями Subversion по следующим причинам:

1. Лёгкая в изучении относительно децентрализованных систем

2. Разработка ведётся централизованным методом на сервере предприятия, децентрализация не нужна

3. Быстрое первичное клонирование репозитория

4. Лёгкость в обслуживании

5. Существование множества как консольных, так и GUI-клиентов

6. Множественное ветвление не требуется

 

Библиографический список

 

1. Walsh, N Muellner Docbook:The Definitive Guide / Norman Walsh, Leonard Muellner // O’Reilly Media, 1999. — 648 p.

2. Walsh, N. DocBook: From Syntax to Publication / Norman Walsh // Washington, DC/ — http://nwalsh.com/docs/tutorials/xml2004/slides.

3. Stayton, B Single-source Publishing with DocBook XSL / Bob Stayton. — Sagehill Enterprises, 2005. — 560 p.

4. Валиков А. Н. Технология XSLT / А. Н. Валиков. — СПб.: БХВ-Петербург, 2002. — 544 c.

5. Глаголев В. А. Разработка технической документации. Руководство для технических писателей и локализаторов ПО/ В. А. Глаголев. — СПб.: Питер, 2008. — 192 с.

6. Бухаров М. Н. Разработка документации для пользователей прикладных программ / М. Н. Бухаров: лекция. — М.: ИКЦ Маркетинг: МУПК, 2002.

7. ГОСТ 2.105-95. Единая система конструкторской документации. Общие требования к текстовым документам

8. ГОСТ 2.601-95. Единая система конструкторской документации. Экс-плуатационные документы

9. ГОСТ 34.003-90. Информационная технология. Комплекс стандартов на автоматизированные системы. Термины и определения

10. Extensi

Приложения

ПРИЛОЖЕНИЕ А

Требования к оформлению документов

Область применения

Настоящие Требования определяют порядок создания, хранения, пред-ставления и использования электронной сопроводительной документации.

Настоящие Требования распространяются на следующий перечень документов:

• Руководство пользователя

• Руководство администратора

• Руководство по эксплуатации

• Руководство разработчика

• Справочное руководство

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

 

Формат документа

 

При создании и хранении документов используется формат HTML.

Использование иных форматов допускается для:

• создания и хранения документов на иностранных языках

• представления и использования документов

• хранения русскоязычных документов при условии параллельного сохранения аутентичной копии в формате HTML

При создании документов не должны использоваться т.н. «каскадные стили» (CSS)

 

Кодировка символов

 

При создании документов используется кодировка KOI8-R

 

Структура электронного документа

 

Электронный документ в формате HTML содержится в каталоге с жестко определенным наименованием, если таковое определено настоящими Требованиями (см. таблицу 1). Переименование каталога в этом случае не допускается. Наименование каталога для документа, не упомянутого в таблице 1, не регламентируется.

Таблица 1

Название документа Название ка-талога

Руководство пользователя АДИС (Linux) adis-u

Руководство администратора АДИС adis-a

Руководство пользователя АДИС (Windows) adis-w

Руководство пользователя комплекса бескраскового датилоско-пирования (Linux) lscan-u

Руководство администратора комплекса бескраскового датило-скопирования (Linux) lscan-a

Руководство пользователя и Руководство администратора ком-плекса бескраскового дактилоскопирования (Windows) lscan-w

Руководство пользователя АБИС «Арсенал» (Linux) arsenal-u

Руководство администратора АБИС «Арсенал» arsenal-a

Руководство пользователя АБИС «Арсенал» (Windows) arsenal-w

Документ может содержать от 1 до 5 уровней озаглавленных структур-ных элементов текста:

1. Разделы

2. Главы

3. Подразделы

4. Пункты

5. Подпункты

Если в разделе или в главе используется дробление на нисходящие структурные элементы, то в начале раздела или главы должно быть приведено его (ее) содержание. Содержание раздела или главы представляет собой список нисходящих структурных элементов с прицепленными относительными ссылками, указывающими на их начало. Допускается размещение содержания на отдельной, стартовой странице. Стартовая страница должна размещаться в одном каталоге с основным текстом. Название стартовой страницы не регламентируется.

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

Раздел

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

Глава

Содержимое каждой главы русскоязычного документа в формате HTML помещается в каталог с уникальным для данного документа именем. Если глава описывает тот или иной программный модуль, название каталога должно совпадать с названием модуля. Название стартовой страницы в формате HTML должно совпадать с названием каталога и содержать расширение имени html.

Подразделы, пункты, подпункты

Как правило, раздел (глава) делится на подразделы. Более подробное деление осуществляется по мере необходимости. Допускается до трех уровней деления раздела — подразделы, пункты, подпункты.

В формате HTML элементы раздела должны быть размещены в каталоге раздела. При этом, допускается размещение элементов раздела как в общем HTML-файле раздела, так и в отдельных HTML-файлах и подкаталогах.

 

Цвет

Цвет текста

Цвет текста не должен задаваться HTML-кодом документа.

Для фона допускается использование в HTML-коде атрибутов цвета со значениями из полутоновой палитры (градации серого).

Цвет иллюстраций

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

 

Шрифт

Пропорциональный (Variable Width) шрифт следует использовать:

• Для заголовков

• Для сплошного текста, в подавляющем большинстве случаев.

Моноширинный (Fixed Width) шрифт следует использовать:

• Для блоков преформатированного текста (тег </pre>)

• Для цитат из конфигурационных файлов и программ

• Для примеров командной строки.

Формат текста

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

Абзац

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

Для образования разделительной пустой строки следует использовать тег <p>. Допускается вместо тега <p> использовать двойной перевод строки:<br><br>.

Разметка внесенных изменений

Для разметки внесенных изменений в составе вспомогательной версии документа («заплатки») используются следующие унифицированные элементы оформления:

• три однонаправленные угловые скобки — >>> — используются в качестве метки для навигации по тексту, содержащему изменения, и для записи комментариев

• Зачеркивание — xxxxxxx — отмечает удаленный текст

• Подчеркивание — xxxxxxx — отмечает добавленный текст.

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

Заголовки

Заголовок раздела (главы) должен быть оформлен тегом <h1> (Heading1), выровнен по центру и заключен между горизонтальными чертами (сверху и снизу).

Заголовок подраздела должен быть оформлен тегом <h2> (Heading2), выровнен по левому краю и дважды сдвинут вправо (теги <blockquote><blockquote>).

Заголовок пункта должен быть оформлен тегом <h4> (Heading4), выровнен по левому краю и однократно сдвинут вправо (тег <blockquote>).

Более мелкое деление текста заголовками не выделяется. Для разделения текста используются названия пунктов, отделенные пустыми разделительными строками.

 

Термины

Уникальность

Для одного понятия внутри одного документа должен использоваться один термин.

Однозначность

Различающиеся понятия должны определяться отличными друг от друга терминами.

Выбор термина

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

1. Термин является стандартным (описан в стандарте, регламентирую-щем данную область техники)

2. Термин является общеупотребительным в данной области техники

3. Термин интуитивно понятен среднестатистическому специалисту в данной области.

Иллюстрации

Изображение, предназначенное для иллюстрирования текста, должно быть записано в файл в формате JPEG или PNG.

Скриншоты

Иллюстрация, полученная путем захвата изображения с экрана (скрин-шот), должна быть записана в файл в исходном масштабе, без преобразования растра.

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

Иллюстрации для HTML-документа

В HTML-документ иллюстрации следует вставлять в исходном масштабе, без преобразования растра.

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

Масштабирование иллюстраций для бумажного документа

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

 

 

ПРИЛОЖЕНИЕ Б

Листинг 1. Пример топика типа concept

<?xml version=»1.0″ encoding=»UTF-8″ ?>

<!DOCTYPE concept

PUBLIC «-//OASIS//DTD DITA Concept//EN» «../../dtd/concept.dtd»>

<concept id=»intro»

xml:lang=»ru-ru»

xmlns:ditaarch=»http://dita.oasis-open.org/architecture/2005/»>

<title>Введение</title>

<prolog>

<copyright>

<copyryear year=»2010″/>

<copyrholder>Компания</copyrholder>

</copyright>

</prolog>

<conbody>

<p>Документ содержит сведения об установке,

настройке и применении программы</p>

</conbody>

</concept>

 

Листинг 2. Пример топика типы task

<?xml version=»1.0″ encoding=»UTF-8″ ?>

<!DOCTYPE task PUBLIC «-//OASIS//DTD DITA Task//EN» «../../dtd/task.dtd»>

<task id=»installprogram»

xml:lang=»ru-ru»

xmlns:ditaarch=»http://dita.oasis-open.org/architecture/2005/»>

<title>Установка программы</title>

<copyright>

</copyright>

</prolog>

<taskbody>

<p>Для того чтобы установить программу на компьютер:</p>

<steps>

<step>

<cmd>

Распакуйте архив <filepath>install.zip</filepath>

в произвольный каталог.

</cmd>

</step>

<step>

<cmd>

Запустите программу <filepath>install.exe</filepath>.

</cmd>

</step>

<step>

<cmd>

Следуйте указаниям, выводимым программой установки на экран.

</cmd>

</step>

</steps>

</taskbody>

</task>

 

Листинг 3. Пример карты документа

<?xml version=’1.0′ encoding=’UTF-8′ ?>

<!DOCTYPE map PUBLIC «-//OASIS//DTD DITA Map//EN» «../dtd/map.dtd»>

 

<map xmlns:ditaarch=»http://dita.oasis-open.org/architecture/2005/»

title=»Руководство пользователя»

xml:lang=»ru-ru» toc=»yes»>

 

<!— Вводный раздел. Вложение тем является

типичным способом построения карты документа—>

<topicref href=»concept/intro.xml»>

<topicref href=»concept/functionality.xml»/>

<topicref href=»topic/symbolicnotation.xml»/>

</topicref>

 

<!—Установка программы —>

<topicref href=»concept/install.xml»>

<topicref href=»concept/complect.xml»/>

<topicref href=»task/installprogram.xml»/>

<topicref href=»concept/copyright.xml»/>

</topicref>

 

<!— Интерфейс пользователя —>

<topicref href=»concept/userinterface.xml» type=»concept»/>

 

<!— Работа с почтой—>

<topicref href=»concept/correspondence.xml»>

<topicref href=»task/correspondence_messagelist.xml»/>

<topicref href=»task/correspondence_createmessage.xml»/>

<topicref href=»task/correspondence_receive.xml»/>

<topicref href=»task/correspondence_reply.xml»/>

<topicref href=»task/correspondence_forward.xml»/>

</topicref>

 

<!— Ведение адресной книги —>

<topicref href=»concept/addressbook.xml»>

<topicref href=»task/addressbook_cards.xml»/>

<topicref href=»task/addressbook_add.xml»/>

<topicref href=»task/addressbook_change.xml»/>

<topicref href=»task/addressbook_delete.xml»/>

<topicref href=»task/addressbook_search.xml»/>

</topicref>

 

<!— Настройка —>

<topicref href=»concept/settings.xml»>

<topicref href=»task/settings_messageeditor.xml»/>

<topicref href=»task/settings_addressbook.xml»/>

<topicref href=»task/settings_messahearchive.xml»/>

<topicref href=»task/settings_crypto.xml» audience=»professional»/>

<topicref href=»task/settings_spam.xml» audience=»professional»/>

</topicref>

 

<!— Приложения —>

<topicref href=»reference/dialogwindows.xml» type=»reference»/>

<topicref href=»reference/netrules.xml» type=»reference»/>

<topicref href=»reference/symbolicsigns.xml» type=»reference»/>

</map>