Примеры case-средств
Если сначала диаграммы рисовались вручную, то в середине 1980-х годов появляются первые продукты, реализующие CASE-технологию. Компания TI (Texas Instruments) выпускает продукт IEF (Information Engineering Facility), компания KW (Knowledge Ware) создает ADW.
Целевыми платформами обоих продуктов были только мэйнфреймы, что являлось их основным недостатком. В 1986 году начинаются разработки продукта HPS (High Productivity System), а в 1990 году образуется компания SEER, которая выпускает HPS на рынок.
Технологии оказались востребованными на рынке: на 1995 год объемы продаж IEF равнялись 200 млн. долл., ADW — 150 млн. долл., HPS — 120 млн. долл. У продукта HPS был более высокий уровень генерации кода (lower case), но более слабый уровень методологии и графических редакторов (upper case).
Лекция 7
Чтобы облегчить этот поиск в линейном потоке информации, существует единственная возможность - разместить сведения о продукте несколькими крупными последовательными и относительно независимыми группами, каждая из которых ориентирована на один из базовых сценариев. Тогда пользователь, выбирая тот или иной базовый сценарий, сразу будет знать, к какой части документации ему обращаться. Довольно естественным нам представляется следующее распределение информации между группами, приблизительно следующим образом:
Группа |
Сценарий |
Пояснения |
Вводные главы |
"Быстрый старт" |
Подготавливают пользователя к чтению всей остальной документации, содержат информацию, которая особенно необходима "торопливому" пользователю: как быстро установить и подготовить к работе программный продукт, как начать работать с ним. Часто включают главу с названием вроде "Как быстро начать работу с..." |
Руководство пользователя |
Ознакомительное чтение |
Пользователь собирается научиться решать наиболее типичные внешние задачи с помощью программного продукта. |
Справочник пользователя |
Получение справок по отдельным элементам программного продукта |
Содержит детальное разъяснение по поводу всех составных частей, функций, элементов интерфейса программного продукта. |
Специальные главы |
Детальное знакомство с программным продуктом |
Сюда могут помещаться такие темы, как: экспорт и импорт файлов, формирование отчетов, поиск данных, сервисные возможности и т. д. |
Легко видеть, что из соображений удобства автор документации излагает сведения о продукте как бы в несколько обходов: сначала минимальные сведения об установке, настройке и запуске, затем описание наиболее типичных задач, затем подробный обзор всех элементов и функций, затем специальные вопросы. Однако необходимо следить за тем, чтобы соблюдалось следующее правило:
Основным средством систематизации сведений в линейном информационном потоке является их структурирование.
Структурирование осуществляется двояким образом: в целом и в отдельных частях текста.
В целом: Сведения располагаются группами, "в несколько обходов". Такая группировка делает удобным переход от одного сценария к другому и поиск нужной группы сведений.
В отдельных частях текста: Сведения располагаются в порядке, определяемом логикой изложения. На основе сведений более общего характера излагаются сведения более частные, более конкретные, причем переход от более общего к более частному подчеркивается многоуровневой рубрикацией.
|
Разрабатывая структуру будущей документации, составьте разметку, как будут распределяться по ним сведения о программном продукте - в целом и в отдельных частях.
|
|
|
Стандартная структура документации как инструмент структурирования информации
|
|
Стандартная структура документации не только не сковывает разработчика в его действиях, но напротив, помогает ему на начальных этапах разработки:
Вводит его в курс основных проблем, которые ему предстоит осветить.
Предоставляет в его распоряжение готовый остов будущей документации.
Позволяет не упустить из виду ни один из важных аспектов документации.
В то же время не следует думать, что стандартная структура - это готовый бланк, в который только вписываются сведения о конкретном продукте.
|
Заголовки разделов и общие принципы их составления |
Играют значительную роль в структурировании информации.
Делают более очевидной общую структуру документации.
Облегчают чтение документации и поиск в ней необходимых сведений
Как правило, заголовок состоит из одной фразы (словосочетания) и коротко обозначает тему раздела, "реферирует" его содержание. Такой порядок составления заголовков восходит к глубокой древности.
Ему противостоит другой, не менее древний, когда текст озаглавливался по нескольким первым словам (как, например, во многих древнееврейских текстах).
Комментарий. В глаза должно бросаться то, что выделяет данный заголовок из общего ряда. Это особенно важно, когда пользователь ищет нужную тему в оглавлении. Зачастую он находит там ряд заголовков, похожих друг на друга.
Например:
Действия с зараженными объектами
Действия с испорченными вирусом объектами
Действия с подозрительными объектами
Ясно, что поиск при этом оказывается затруднен: главное слово, оно же первое слово заголовка, всюду одно и то же, а различие между заголовками прячется где-то в поясняющих словах. Каждый в отдельности заголовок составлен вполне грамотно, однако оглавлением будет пользоваться неудобно.
Лучше так:
Зараженные объекты и действия с ними
Испорченные вирусами объекты и действия с ними
Подозрительные объекты и действия с ними
Одно из основных требований к тексту документации состоит в том, что этот текст должен отличаться высокой степенью формализации. Изложение должно быть по возможности строгим, единообразным, логически последовательным, состоящим по большей части из готовых формул - так что у иного ценителя изящной словесности может возникнуть желание как-то разнообразить его. Но вот это как раз и может оказаться неуместным. Чтобы объяснить, зачем нужна формализация изложения, приведем простой пример. Почему официальные документы всегда составляются не произвольным образом, а по определенной, четко регламентированной форме? Порой кажется, что это нелепая прихоть бюрократов, но это далеко не так. Дело в том, что каждый документ описывает ситуацию, которая в большинстве аспектов похожа на другие аналогичные ситуации и лишь в некоторых аспектах - уникальна. Поэтому ситуация описывается так, чтобы чиновник или юрист мгновенно опознавали в этой ситуации типичные признаки (которые описываются знакомыми формулами) и на их фоне сразу выделяли суть конкретного дела. В противном случае ему бы пришлось каждый раз подробно анализировать сложный и запутанный текст, задерживать внимание на несущественных деталях и т. д. Это бы окончательно застопорило и без того небезупречную бюрократическую машину. Формализация изложения является важнейшим средством, которое позволяет:
Формализация изложения позволяет пользователю быстро и по большей части бессознательно рассортировать информацию, с первого взгляда опознать знакомые или типичные действия, процедуры, проблемы и т. д. Напротив, отсутствие должной формализации изложения заставляет его каждый раз вникать в ситуацию как в совершенно новую, не имеющую аналогов. Вот почему формализация упрощает работу с документацией. Формализованное изложение сразу дает понять пользователю, что автором документации является квалифицированный специалист (подобно тому как, взяв в руки документ, составленный профессиональным юристом, Вы сразу подсознательно проникаетесь к нему уважением). Наконец, формализация облегчает сам процесс написания документации, предотвращает попытки каждый раз заново (и зачастую неудачно) искать средства выражения для типичных, часто встречающихся ситуаций. Разве не проще использовать то, что уже было создано до нас? И разве не проще, раз описав какую-то ситуацию, пользоваться этим описанием на протяжении всего изложения? Разумеется, проще, - и Вам, и пользователю.
Формализация изложения начинается с унификации языка. Техническая документация не роман, где ценится неповторимая оригинальность языка и новизна образа. Здесь царит критерий унификации языка:
Прежде всего, это касается терминологии - терминологии внешней области, компьютерной терминологии и специфической терминологии. Все три уровня терминологической лексики должны быть продуманы и унифицированы. Термины, не включенные в стандарт, должны быть продуманы и унифицированы Вами самостоятельно.
До сих пор (Главы 1-4) мы почти все время двигались только в одном направлении и смотрели, фигурально выражаясь, почти исключительно вперед - как написать хорошую документацию. Однако на практике приходится постоянно оглядываться на уже сделанное, подвергать свою работу оценке, опознавать ошибки и исправлять их. Но чтобы находить и исправлять ошибки, необходимо хотя бы приблизительно представлять себе их перечень. Вот почему мы решили представить здесь реестр наиболее распространенных ошибок и недочетов - реестр, в который самой жизнью, увы, будут вноситься новые и новые дополнения. Мы выделяем ошибки и недочеты следующих видов:
Необходимо тестировать документацию с целью выявления в ней несоответствий между реальным продуктом и его описанием. Для крупных проектов эта задача не только не может быть осуществлена в одиночку, но и требует особых методик. Такие методики существуют и активно используются разработчиками документации; разработаны также специальные программные пакеты, относящиеся к классу CASE-систем и реализующие эти методики.
Под логико-стилистическими ошибками и недочетами мы понимаем такие погрешности стиля, которые, по сути дела, не зависят от конкретного языка. Они связаны с неправильным отражением в документации логических отношений между различными элементами описания. Следует сразу подчеркнуть: речь идет не о настоящих логических ошибках, а о недоразумениях, которые возникают в результате неумелого выражения логических отношений в языке и которые ведут в самом лучшем случае к определенным трудностям при чтении и использовании документации, а в худшем - к неверному пониманию или вообще к отсутствию такового.
Под стилистическими ошибками и недочетами мы понимаем такие погрешности, которые связаны с конкретным языком, его словарем, конкретным набором стандартных клише, правилами и нормами и т. д. Эти погрешности нами рассматриваются как собственно стилистические.
Нестандартное описание, слово или термин Наименование ошибки Употребление нестандартного термина Комментарий Особенно часты замены стандартных терминов на употребительные в повседневной речи программистов: "иконка", "флажок" и т. д. Стоит также обратить внимание на нестандартные формы склонения слов; например: "сервер" вместо "серверы" Как исправить Заменить термин на правильный
Наименование ошибки Употребление нестандартных околотерминологических слов Комментарий С каким-либо термином употреблено неправильное околотерминологическое слово Примеры Чтобы выполнить процедуру, нажмите на значок [вместо: щелкните мышью по значку] Как исправить Замените слово
Наименование ошибки Употребление нестандартных конструкций для описания процедур Комментарий Описание процедуры, для которой существует стандартное клише, выполнено не в соответствии со стандартом. Как исправить Употребить правильное клише
Переусложненная синтаксическая конструкция Наименование ошибки Лишняя служебная часть речи Комментарий Иногда служебная часть речи оказывается лишней, ее можно заменить беспредложной или бессоюзной конструкцией. Примеры Администратор может назначать администраторов для своей группы, а также для любых групп, которые входят в нее на любом уровне иерархии.[предлог ДЛЯ может быть убран] Как исправить Убрать лишние служебные части речи
Тавтология -Неблагозвучный повтор одинаковых, однокоренных или сходных по звучанию слов Примеры Для того чтобы установить цвет фона, нажмите на кнопку "Цвет фона", после чего в диалоговом окне "Цвет фона" выберите в списке "Цвет фона" цвет фона Как исправить Заменить значимое слово синонимом или местоимением
Наименование ошибки Повторы однокоренных и созвучных слов Комментарий Как стилистический дефект звучат близкие сочетания однокоренных или созвучных слов: Примеры Следует следить Позволяет пользователю пользоваться При применении И имеет На наличие Как исправить Заменить одно из слов синонимом или переработать всю конструкцию
Наименование ошибки Дефекты ритмики Комментарий Можно выделить два случая: Под ударением два или несколько раз оказывается одно и то же слово. Возникновение "поэтического" звучания текста - избыточная ритмичность, внутренняя рифма Примеры Для того чтобы изменить настройки, хранящиеся в файле настройки Включение и отключение режима лечения Как исправить Заменить одно или несколько из повторяющихся слов синонимами. Перестроить фразу в другом ритме.
ГОСТ Р (проект, 1-я редакция) Проект, 1-я редакция 1 НАЦИОНАЛЬНЫЙ СТАНДАРТ РОССИЙСКОЙ ФЕДЕРАЦИИ Информационные технологии Системная и программная инженерия СТИЛЬ ИЗЛОЖЕНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ ПРОГРАММНОГО СРЕДСТВА Общие требования Information technology. System and programming engineering. Style of user documentation. General requirements Дата введения — ________________ 1. Область применения 1.1. Настоящий стандарт устанавливает общие требования к стилю изложения доку-ментации пользователя программного средства, разработанной и поставляемой на рус-ском языке. 1.2. Настоящий стандарт в целом распространяется только на документацию пользо-вателя и только пользователя программного средства. 1.2.1. Настоящий стандарт не распространяется на другие виды программной и техни-ческой документации. В то же время отдельные положения настоящего стандарта могут распространяться на другие виды программной и технической документации. 1.2.2. Настоящий стандарт распространяется на любые виды документации пользова-теля. Стандарт содержит требования и рекомендации к стилю изложения документов, представленных на любых носителях данных и выполненных как в виде обычного текста, так и в виде гипертекста (контекстная справка, документация, размещенная в Интернете или на интранет-сервере). В то же время стандарт ориентирован в первую очередь на до-кументы, выполненные печатным способом в виде обычного текста. Требования, предъ-являемые к структуре документа, существенным образом различаются для обычного тек-ста и гипертекста. Настоящий стандарт не содержит никаких специальных требований и рекомендаций, относящихся к гипертексту; оговорки относительно специфики последнего сделаны в тексте настоящего стандарта там, где это необходимо. 1.3. Настоящий стандарт применяется в отношении документации пользователя, раз-рабатываемой либо внутри той или иной организации одним или несколькими документа-торами, либо одной организацией (документатором) по заказу другой организации (заказ-чика). Нормативные ссылки В настоящем стандарте использованы нормативные ссылки на следующие стандарты и классификаторы: ГОСТ 2.105-95 Единая система конструкторской документации. Общие требования к текстовым документам ГОСТ 19.105-78 Единая система программной документации. Общие требования к программным документам ГОСТ 19.106-78 Единая система программной документации. Требования к про-граммным документам, выполненным печатным способом ГОСТ Р ИСО/МЭК 12119-2000 Информационная технология. Пакеты программ. Тре-бования к качеству и тестирование ГОСТ Р ИСО/МЭК 12207-2000 Информационная технология. Процессы жизненного цикла программных средств ГОСТ Р ИСО/МЭК 15910-2002 Информационная технология. Процесс создания доку-ментации пользователя программного средства
Единство терминологии Единство терминологии предполагает следующие правила: – каждый термин всегда употребляется в одном и том же значении; – никакие два (или более) термина не употребляются в одном и том же значении; – каждый термин сочетается с другими терминами и прочими словами в соответствии с одними и теми же синтаксическими моделями.
|
|
||||||||||||||||
|
|
