Диссертация (1149623), страница 15
Текст из файла (страница 15)
Следует отметить, что использование найденных групп неточных повторов в рамках организации формальногопереиспользования текста возможно только сторонними средствами в том случае, если документация представлена в других форматах, которые поддерживают данную возможность [76, 110, 111].Главным результатом третьей фазы является улучшенная документация. Дополнительным результатом третьей фазы могут быть рекомендации по написанию документации и шаблоны фрагментов документации, созданные на базенайденных документации повторов.
Эти рекомендации и шаблоны важны длядальнейшей разработки документации: располагая ими, технический писатель,описывая те или иные сущности, может не сверяться с существующими описаниями, а сразу получать информацию о том, каким образом следует структурировать новый текст. На схеме метода эти рекомендации обозначены пунктиром,так как их выработка и автоматизация работы с ними выходят за рамки даннойдиссертационной работы.Опишем подробнее, каким образом предложенный метод может быть использован для повышения качества документации. Для этого мы используем ряд показателей качества документации, предложенных в [153].
Рассмотрим эти показатели.Структура документа (information organization, document structure). Этотпоказатель характеризует то, насколько хорошо организована представленная вдокументе информация, на сколько у документа чёткая структура. Этот показатель является высоким, когда структура чёткая, а информация организована таким образом, что читателю легко воспринимать документ.83Оформление (format, writing style). Этот показатель характеризует качествоформатирования документа и общую стилистику. На него влияет единообразноеиспользование поясняющих иллюстраций, качество вёрстки и т.д. Стилистика ивёрстка документа являются важными для читателя: хорошо оформленный текстлегко читать и воспринимать.
Также важно и наличие легко воспринимаемыхиллюстраций (диаграмм, графиков), которые упрощают понимание информации, изложенной в документе.Грамотность (Spelling and grammar) — отсутствие орфографических играмматических ошибок. Показатель грамотности также важен, т.к. большоеколичество грамматических и орфографических ошибок затрудняют восприятиетекста, снижают мотивацию читателя.Перечисленные показатели могут быть значительно улучшены при помощиуправления повторами.Первый показатель (структура документа) улучшается следующим образом.Справочная документация описывает большое количество однотипных сущностей, поэтому для описания их свойств используются единообразные разделы ипорядок информации в этих разделах.
Следует отметить, что данная структуране может быть зафиксирована только оглавлением. Более того, эта структуравключает в себя некоторое количество общего текста. Например, описание каждого класса может начинаться с одной и той же следующей фразы: «Данныйкласс предназначен для …». Описание параметров функции может иметь следующий вид: «Функция имеет … параметров.
Первый параметр означает … Второйпараметр означает …».В тех случаях, когда описание однотипных сущностейне стандартизовано таким образом, структура документации обычно нуждаетсяв переработке. В итоге, в документации мы получаем большое количество неточных повторов. Эти повторы могут быть могут быть задействованы при организации повторного использования.Второй показатель (оформление) улучшается путём унификации специфичного для документации языка и стиля: подписей к иллюстрациям, приглашенийк рассмотрению примеров кода, информации об авторах, перекрёстных ссылок и84т.д. — все это должно быть единообразным. Также производится унификацияформатирования (например, выделение терминов полужирным шрифтом иликурсивом), т.к.
несообразности в форматировании обычно хорошо видны прианализе неточных повторов.Третий показатель (грамотность) улучшается, когда технический писательанализирует различия неточных повторов: орфографические, грамматические ипунктуационные ошибки часто попадают в вариации или же замечаются привнимательном чтении различных фрагментов текста в ходе анализа. Отметим,что не только грамотность, но и другие ошибки попадают в вариации неточныхповторов. По мере их исправления растёт уровень повторного использования.Многие другие показатели, перечисленные в [153], такие, как точность, согласованность (единообразие и целостность), корректность, читаемость и т.д. такжекосвенно улучшаются в результате управления повторами.4.2.
Автоматизированный рефакторинг DocBook-документацииОпишем автоматизированный рефакторинг документации в формате DocBook, осуществляемый на основе найденных повторов.Повторы, автоматически найденные в DocBook-документах (первая фаза насхеме метода, рис. 4.1.1), можно использовать в качестве исходных данных дляавтоматического рефакторинга (третья фаза метода), поскольку они являютсягруппами сходных текстовых фрагментов, в явном виде содержащих архетип идельту. Вследствие последнего факта группу неточных повторов можно представить средствами языка DRL в виде одного текстового шаблона с набором точекрасширения и соответствующими значениями.Среди автоматически найденных групп повторов пользователь может выбратьгруппы, заинтересовавшие его в смысле переиспользования. Важно, чтобы повторно используемые фрагменты текста были осмысленными, являясь частьюописания функции, прерывания, типа данных и т.д.
Выбрав одну из найденныхгрупп, пользователь может создать на её основе переиспользуемый фрагменттекста — информационный элемент или словарь [11, 21]. При этом применяется85подход к рефакторингу, описанный в [23]. На основе точной группы можно создать информационный элемент или словарь, на основе неточной — только информационный элемент.При рефакторинге выполняется следующая последовательность действий.1. Создаётся описание переиспользуемой сущности (информационного элемента или словаря), как это показано на листинге 1.6.2.2.
Далее, все повторы выбранной группы заменяются ссылками на это описание, как это показано на листинге 1.6.3. В случае неточных повторов каждая ссылка параметризуются соответствующими значениями точек расширения (см. определение 2.1.10).3. Координаты вхождений в документ повторов всех оставшихся групп пересчитываются в соответствии с внесёнными в текст изменениями, чтобы инструмент мог корректно осуществлять навигацию по исходному тексту документа.Текстовые фрагменты, входящие в группу повторов, к которой применяетсярефакторинг, могут не быть корректными с точки зрения синтаксиса DocBook.Например, в листинге 4.2.1 повтором является выделенный полужирным курсивом фрагмент — очевидно, что он нарушает DocBook-разметку, так как содержит лишь закрывающий тег «</emphasis>» и не содержит открывающего.<emphasis>INI-file reader</emphasis> example illustrates a basic use of loading configuration data from a file.
In this example there are configuration data for both a production system and for a staging system. Because the staging system configuration data arevery similar to those for production, the staging section inherits from the production section.Листинг 4.2.1. Повтор, нарушающий разметку DocBookDocBook/DRL-документ после рефакторинга должен оставаться корректным,но, как мы видим в примере выше, разметка документа может быть нарушенапри рефакторинге. Для этого при рефакторинге выполняется балансировка нарушенной разметки — добавляются соответствующие открывающие и закрывающие теги как в выделенном фрагменте, так и в исходных местах его вхождения.86Пример результата балансировки тегов в определении и применении повторноиспользуемого элемента (в нотации DRL) представлен на листинге 4.2.2; добавленные при балансировке теги выделены курсивом.<infelement id="reader_example"><emphasis>reader</emphasis> example illustrates a basic use of loading configuration datafrom a file.
In this example there are configuration data for both a production system and for astaging system.</infelement>……<emphasis>INI-file</emphasis><infelemref infelemid = "reader_example"/> Because the staging system configuration data are very similar to those for production, the staging section inheritsfrom the production section.Листинг 4.2.2. Пример сбалансированной после рефакторинга разметкиОтметим, что полноценная реализация такой балансировки весьма сложна.Так, например, если мы лишний раз откроем и закроем тег «<para>» (задаёт параграф), то в результирующем документе DocBook получим два параграфа вместо одного, что изменит структуру DocBook-документа и его внешний вид. Всилу последнего данное действие в этом случае не будет рефакторингом.В некоторых случаях можно довольно просто сбалансировать разметку, исключив из повтора открывающий/закрывающий тег, подобный «<para>», еслиповтор начинается/закрывается этим тегом.
Но в случае, когда повторы содержаттакие теги в середине, применить такую простую балансировку тегов не представляется возможным. Задача балансировки разметки в общем случае не решенав данной диссертационной работе.4.3. Пример использования методаРассмотрим применение метода управления повторами на примере улучшенияруководства пользователя для одной индустриальной системы. В документе описывается среда моделирования систем крупного предприятия [10]. Моделирование осуществляется при помощи десяти графических редакторов, которые позволяют редактировать модели различных видов. При анализе повторов данного87документа было установлено, что функциональность пяти редакторов, практически, идентична (различаются лишь названия моделей и мелкие детали). Тем неменее, различия в соответствующих фрагментах текста были существенными.После унификации этих фрагментов в среднем была достигнута их схожесть 82%(среднее отношение длины архетипа в символах к длине всего описания).Опишем подробнее улучшение показателей качества документации во времяуправления повторами.1.
Структура документа. При создании описания данных редакторов были раскопированы три фрагмента текста. Затем структура этих фрагментов была существенно переработана разными техническими писателями. В похожихфрагментах были по-разному упорядочены некоторые параграфы.
Наблюдался беспорядок и с иллюстрациями: для некоторых фрагментов соответствующие иллюстрации отсутствовали. Также в некоторых повторах отсутствовали некоторые предложения и последовательности предложений, которые должны были присутствовать во всех повторах группы. Обычно это былизамечания, предупреждающие пользователя о возможных типичных ошибкахпри работе с ПО. Эти дефекты были обнаружены при управлении повторамии устранены путём внесения в документ 25 исправлений.2. Форматирование. Были проанализированы различия в описании одинаковыхдействий и сущностей. По результатам анализа эти описания были унифицированы. Типичный пример различия в описании действия пользователя —«Затем нажмите "Далее"» и «Затем нажмите кнопку "Далее"».
Также былиустранены различия в использовании выделения текста полужирным шрифтом и курсивом в повторяющихся фрагментах текста. Всего по найденнымразличиям было сделано 11 исправлений.3. Грамотность. Были исправлены орфографические и пунктуационныеошибки. Всего было внесено 15 исправлений.Документ, на базе которого построен этот пример, хоть и носит преимущественно справочный характер, всё же не настолько формализован, как, например,типичная API-документация. В нём содержится много развёрнутых описаний88действий пользователя. Соответственно, многие найденные повторы были достаточно большими (несколько предложений). Объём документа в формате «плоского» текста составляет 180 Кб. Количество правок (51), внесённых в документпри управлении повторами, позволяет говорить об эффективности предложенного метода.89Глава 5.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
