На определенном этапе развития программной системы неизбежно возникает задача разработки пользовательской документации. И тут возникает технический вопрос выбора форматов и инструментов разработки документации.
1.1. Выходные форматы
С выбором конечного формата обычно проблем не возникает, так как целевая операционная система предъявляет свои требования. Так, например, для программ для Windows — это формат скомпилированной справки CHM, для Linux и BSD систем — это man. Общим для всех систем форматом для онлайн справки является html, а для печати — pdf.
1.2. Исходные форматы
Несмотря на кажущуюся очевидность необходимости использования специально созданных программ, здесь не все так однозначно.
В зависимости от целевой операционной системы подходы отличаются.
1.2.1. Проприетарные исходные форматы
Так, для создания скомпилированной справки для Windows в формате chm Microsoft предлагает использовать специальный бесплатный компилятор HTML Help Workshop. При этом исходные тексты должны быть подготовлены в формате html (редактор в поставку не входит), а файлы оглавления — в специфическом формате. Никаких средств формирования печатных руководств не предоставляется.
Разумеется, специализированные программы для создания справки (Robohelp, HelpManual) схема его остается закрытой и никак не задокументированной.
Технологическая документация в проекте
На сегодняшний день таких форматов несколько:
- ASCIIdoc, используемый дефакто в Linux (BSD) системах;
- Wiki, применяемый в различного рода энциклопедиях и даже давший им общее название;
- MarkDown — так сказать, «многоцелевой» формат документирования.
Все эти разметки используют некоторый символьный нетеговый набор правил оформления заголовок, иллюстраций и ссылок, предполагающий редактирование в простых текстовых редакторах. Подготовка же пригодного к просмотру вида осуществляется программно как правило на стороне сервера.
Например, Википедия преобразует Wiki-формат в HTML «на лету». Веб-портал системы Git http://github.org также способен показывать документы в разметке Markdown в пригодном для чтения в браузере виде.
1.3. Редакторы
Несмотря на то, что для создания и редактирования исходных текстов достаточно возможностей блокнота, некоторые сервисные функции, такие как проверка правописания и подсветка разметки были бы писателю весьма кстати.
В статье http://www.ixbt.com/soft/markdown-online-2.shtml приведен обзор онлайн-редакторов поддержкой markdown-синтаксиса, а в http://www.ixbt.com/soft/markdown-online-3.shtml приведен обзор пяти настольных редакторов, поддерживающих формат markdown по умолчанию, так сказать «из коробки».
Лекция 1. Техническая документация.
Одним из таких редакторов является MarkdownPad.
1.3.1. MarkdownPad
Рисунок 1. Редактор MarkdownPad 2
Как видно из копии экрана, редактор MarkdownPad 2 поддерживает «живой» предварительный просмотр редактируемого файла с поддержкой синхронной прокрутки исходного текста и результата рендеринга.
При установке на Windows 8 может возникнуть ситуация, когда предварительный просмотр недоступен.
Рисунок 2. Сообщение о крахе системы предварительного просмотра
По заявлению разработчиков http://markdownpad.com/faq.html#livepreview-directx это связано с необходимостью установки специфического SDK веб-рендеринга Awesomium 1.6.6 SDK, который в свою очередь использует DirectX.
Редактор поддерживает подсветку синтаксиса, проверку синтаксиса одного языка (в том числе русского), экспорт в форматы HTML, PDF (только в платной версии). Иными словами, MarkdownPad 2, как и другие специальный редакторы, является хорошим выбором для технического писателя. В тех же случаях, когда пользователю предстоит редактировать файлы различного формата, можно адаптировать свой редактор и для редактирования текстов с markdown-разметкой.
1.3.2. Notepad++
Редактором, в достаточной мере отвечающим этим требованиям, можно считать Notepad++. Проверка правописания многих языков поддерживается с помощью специального плагина. Причем поддерживается проверка текста на нескольких языках одновременно.
Рисунок 3. Редактор Notepad++
Несмотря на простоту правил разметки, автору текстов было бы удобней работать с подсветкой синтаксических элементов. Применительно к Notepad++ в этом поможет проект Markdown Syntax Highlighting for Notepad++, который, по сути, представляет собой конфигурационный файл пользовательского языка Markdown. После его установки текст в редакторе выглядит следующим образом.
Рисунок 4. Редактор Notepad++ с подсветкой элементов разметки markdown
1.4. Quota
Примечательно, что редакторы с поддержкой markdown существуют даже для мобильных платформ. На рисунке приведена копия экрана смартфона с запущенным редактором Quoda Code Editor.
Рисунок 5. Quoda Code Editor — универсальный редактор для Андроид с поддержкой разметки markdown
Следует сказать, что большая часть этой статьи набрана именно в этом редакторе, а уже потом выгружена на компьютер для доработки.
По результатам анализа возможностей языка разметки Markdown и специальных редакторов можно рекомендовать их применение для документирования систем средней сложности.
1.4.1. Открытые теговые форматы
Вместе с тем, для разработки программной документации больших систем следует применять в качестве исходного формата открытый, хорошо документированный формат. В качестве средства формирования — инструмент с широкими возможностями по настройке внешнего вида, профилирования и способностью формировать документы в различных форматах.
Этим требованиям в полной мере отвечают такие системы как DITA и Docbook.
Несмотря на некоторые различия, обе системы имеют много общего:
- используют в качестве исходного формата документированный (схематизированный) XML, что обеспечивает возможность использования для редактирования любого XML-редактора с функцией валидации;
- для конвертирования в один из результирующих форматов может быть использован практически любой xsl-преобразователь xslproc, xalan, saxon и др.;
- для получения pdf-документа используется промежуточный формат xsl-fo, из которого средствами любого fo-процессора (например, Apache FOP или XEP) уже формируется pdf;
- для настройки внешнего вида и профилирования используются многочисленные параметры преобразований, а в случае необходимости — добавлением пользовательских xsl-шаблонов.
Следует особо подчеркнуть, что данные системы используют семантическую разметку в исходных документах. Внешний вид же выходного документа определяется правилами и параметрами преобразований. Такой подход позволяет на этапе написания исходных текстов автору не задумываться над типографикой и дизайном, а сосредоточиться исключительно на смысловом содержании.
Вместе с тем практический опыт использования, в частности Docbook, подтвержденный и в ряде публикаций, показал, что и при использовании столь продуманной технологии возникают некоторые сложности:
- создание исходных текстов в формате XML определенной схемы требует от технического писателя навыков работы со специальными редакторами;
- хорошие XML-редакторы с поддержкой Docbook — продукты коммерческие и недешевые (например, oXygen XML Editor, Altova XMLSpy XML Editor);
- богатые возможности XML-разметки влекут за собой усложнение формата. Например, для вставки в текст иллюстрации с подписью в разметке Docbook необходимо использовать четыре вложенных тега.
Естественно, что вышеперечисленные недостатки сдерживают широкое применение XML-ориентированных технологий единого источника.
В случае использования нетеговых форматов для подготовки офлайн или печатной документации необходимо использовать утилиты преобразования. Среди многих конвертеров особого внимания заслуживает программа pandoc.
1.5. Утилита преобразования pandoc
Pandoc представляет собой кроссплатформенную программу с командным интерфейсом, способную преобразовывать тексты в самых разнообразных разметках в многочисленные выходные форматы.
Так, например с использованием pandoc можно конвертировать исходные документы в разметках ASCIIdoc, Wiki, Markdown в HTML. Если установить LaTex, то становится возможным получение и PDF.
Так, например, преобразование исходного текста этой статьи в html формат можно выполнить следующей командой:
pandoc -f markdown pandoc.md -t html -o pandoc.html -H h.html
Результатом будет готовый html-файл:
Рисунок 6. HTML-документ, сформированный из Markdown утилитой pandoc
За свою универсальность программа образно названа автором «швейцарским армейским ножом».
Действительно, pandoc справляется с конвертированием без каких-либо потерь информации. При конвертировании из формата MarkDown поддерживается чтение трех параметров метаданных — заголовка, автора и даты документа. Поддерживается также передача параметров командной строки для установки некоторых специфических свойств, например языка документа. Есть возможность задать свой шаблон выходного документа, до некоторой степени видоизменяя его.
Так, например, в приведенном выше примере подразумевается, что в текущей папке есть файл h.html, который играет роль заголовка. Если в этом файле добавить ссылку на стилевой файл и, определив , получим следующий результат:
Рисунок 7. HTML-документ, сформированный pandoc с использованием заголовочного файла со ссылками на стили
Как видно из примера, заголовки приобрели свой стиль, а внешние ссылки стали открываться в новой вкладке браузера.
Вышеописанные возможности формата делают оправданным использования разметки Markdown для документирования относительно небольших программных систем, к оформлению которых не предъявляется требований ГОСТ, что и доказывается ее широким использованием в системе Git.
Что же касается больших систем с обширной и сложной документацией, то для ее создания видится применение системы единого источника Docbook. Могут иметь место и переходные случаи, когда масштаб проект проявляется не сразу.
1.6. Docbook
Сложность создания исходных XML-источников можно преодолеть путем использования исходных текстов в формате Markdown с последующим их конвертированием в Docbook. Такое преобразование поддерживается утилитой pandoc. Так, команда
pandoc -f markdown pandoc.md -t docbook -o pandoc4.xml -H h.xml
Использование заголовочного файла h.xml (можно просто пустого) необходимо для корректной обработки метатегов и формирования статьи.
Рисунок 8. Сформированная статья в XML-редакторе
Следует отметить несколько дополнительных требований к разметки markdown, которая будет использована для преобразования в docbook:
Во-первых, следует избегать использования в тексте символов угловых скобок (< и >), так как в XML они используются для выделения тегов, а конвертер оставляет их как есть. Если же угловые скобки нужны по смыслу, то следует использовать сущности < и > .
Во-вторых, при вставке рисунка обязательно вводить альтернативный текст, так как pandoc использует его для создания обязательного тега title у тега figure .
Однако выходной текст формируется в устаревшем формате Docbook 4 версии, в то время как современная 5 версия предоставляет существенно более богатые возможности по семантической разметке.
Для преобразования текста из 4 в 5 версию можно воспользоваться специальным преобразованием db4-upgrade.xsl, входящим в комплект поставки Docbook.
xsltproc -o pandoc5.xml db4-upgrade.xsl pandoc4.xml
Полученный таким образом xml файл схемы docbook 5 можно использовать при формировании единого источника.
Рисунок 9. Cтатья схемы в XML-редакторе в режиме автора
Описанная цепочка преобразований может показаться на первый взгляд длинной и неоправданно сложной. Однако освоив один раз необходимые инструменты и разработав для часто выполняемых задач командные файлы (скрипты) можно сэкономить значительное количество времени в дальнейшем.
Следует особо подчеркнуть, что технология единого источника обладает ярко выраженным кумулятивным эффектом. Начальные временные затраты на разработку типовых неоднократно используемых фрагментов текста окупаются при их использовании в последующих проектах. Именно это качество делает особо привлекательным технологию единого источника при документировании серийных программных систем.
Набор преобразований Docbook поддерживает формирование документов в HTML со стилями, PDF для печати так сказать «из коробки».
xsltproc -o pandoc5.fo c:\fodocbook.xsl pandoc5.xml
Внешний вид выходных документов может быть до определенной степени настроен с помощью параметров. Полученные файл формата FO-XSL pandoc5.fo является промежуточным и нужен для построения конечного PDF.
Немаловажна и возможность автоматического формирования оглавления, списка иллюстраций, листингов, таблиц, индексного указателя, глоссария терминов и списка литературы.
При большом количестве документов в составе пакета также возможно создание отдельного списка с возможностью автоматического формирования правильно оформленных ссылок на них. В случае же подготовки типографского макета руководства с учетом особых требований, например ГОСТ, необходимо разработать дополнительные xsl для форматов обычных страниц, титульной и финальной страницы.
Это может стать темой следующей статьи.
- Разработка веб-сайтов
- HTML
Источник: habr.com
Документирование программы
Последней составляющей процесса программирования является документирование. Оно включает широкий спектр описаний, облегчающих процесс программирования и обогащающих результирующую программу. Постоянное документирование должно составлять неотъемлемую часть каждого шага программирования.
Постановка задачи, проектные документы, алгоритмы и программы – все это документы. Внутренняя документация, включенная непосредственно в программу, облегчает чтение кода. Назначение учебного пособия (еще одной формы документации) – научить пользователя применять новую программу; справочное руководство позволяет ознакомиться с описанием команд программного обеспечения.
При разработке программы создается большой объем разнообразной документации. Она необходима как средство передачи информации между разработчиками программы, как средство управления разработкой программы и как средство передачи пользователям информации, необходимой для применения и сопровождения программы.
Пользовательская документация программы
Пользовательская документация программы объясняет пользователям, как они должны действовать, чтобы использовать данную программу. Она необходима, если программа предполагает какое-либо взаимодействие с пользователями. К такой документации относятся документы, которыми руководствуется пользователь при установке программы.
Состав пользовательской документации зависит от аудиторий, на которую ориентировано данное ПО, и от режима использования документов. Аудитория – это пользователи, у которых есть необходимость в определенной пользовательской документации. Хороший пользовательский документ зависит от правильного выбора аудитории, для которой он предназначен.
Качество пользовательской документации существенно определяет успех самой программы. Она должна быть достаточно просто, понятна и удобна для пользователя. Поэтому не редко к созданию конечного варианта документации не редко привлекаются профессиональные технические писатели. Кроме того, для обеспечения более качественной пользовательской документации разработан ряд стандартов, в которых предписывается порядок разработки этой документации.
Понравилась статья? Добавь ее в закладку (CTRL+D) и не забудь поделиться с друзьями:
Источник: studopedia.ru
4. Документирование программы
Последней составляющей процесса программирования является документирование. Оно включает широкий спектр описаний, облегчающих процесс программирования и обогащающих результирующую программу. Постоянное документирование должно составлять неотъемлемую часть каждого шага программирования. Постановка задачи, проектные документы, алгоритмы и программы – все это документы. Внутренняя документация, включенная непосредственно в программу, облегчает чтение кода. Назначение учебного пособия (еще одной формы документации) – научить пользователя применять новую программу; справочное руководство позволяет ознакомиться с описанием команд программного обеспечения. При разработке программы создается большой объем разнообразной документации. Она необходима как средство передачи информации между разработчиками программы, как средство управления разработкой программы и как средство передачи пользователям информации, необходимой для применения и сопровождения программы. 4.1 Пользовательская документация программы Пользовательская документация программы объясняет пользователям, как они должны действовать, чтобы использовать данную программу. Она необходима, если программа предполагает какое-либо взаимодействие с пользователями. К такой документации относятся документы, которыми руководствуется пользователь при установке программы. Состав пользовательской документации зависит от аудиторий, на которую ориентировано данное ПО, и от режима использования документов. Аудитория – это пользователи, у которых есть необходимость в определенной пользовательской документации. Хороший пользовательский документ зависит от правильного выбора аудитории, для которой он предназначен. Качество пользовательской документации существенно определяет успех самой программы. Она должна быть достаточно просто, понятна и удобна для пользователя. Поэтому не редко к созданию конечного варианта документации не редко привлекаются профессиональные технические писатели. Кроме того, для обеспечения более качественной пользовательской документации разработан ряд стандартов, в которых предписывается порядок разработки этой документации. 4.2 Документация по сопровождению программы Документация по сопровождению программы описывает программу с точки зрения её разработки. Эта документация необходима, если программа предполагает изучение того, как она сконструирована. Сопровождение – это продолжающаяся разработка, поэтому если созданную программу совершенствуют и обновляют не сами её создатели, то чаще всего привлекают специальную команду разработчиков – сопроводители. Этой команде придется иметь дело с такой же документацией, с той лишь разницей, что им нужно будет подробно просматривать и изучать документацию, созданную первоначальными (основными) разработчиками, с той целью, чтоб понять строение и процесс разработки изменяемой программы, и внести в эту документацию необходимые изменения, повторяя в значительной степени технологический процессы Руководство по сопровождению программы, которое описывает известные проблемы вместе с программой, описывает, какие части программы являются аппаратно и программно зависимыми. 5. Запуск готовой программы и анализ полученных результатов — после полученного нами файла с *.exe (обычно) разрешением мы можем запустить его и ещё раз проверить (проанализировать) верно, ли работает программа. На этом этапы создания программы закончены. Структура хранения информации на жёстком диске, кластеры и файлы Чтобы данные можно было не только записать на жесткий диск, а потом еще и прочитать, надо точно знать, что и куда было записано. То есть, у всех данных должен быть адрес. НО: если запоминать отдельно каждый адрес, в который были записаны байты данных, то хранить эти адреса станет труднее, чем сами данные. К СЧАСТЬЮ: информация хранится не байтами, а файлами. Файл – наименьшая единица хранения данных. Каждый файл имеет свой адрес. Чтобы у каждого файла на диске был свой адрес, диск разбивают на дорожки, а дорожки разбивают на секторы (объем сектора – 512 байт) Разбиение диска на дорожки и секторы называется форматированием диска Форматирование – создание физической и логической структуры диска. Ф



- отказ одного из узлов не влияет на работу сети в целом;
- сеть легко настраивать и конфигурировать;
- сеть устойчива к неисправностям отдельных узлов.
Недостатки сетей шинной топологии:
- разрыв кабеля может повлиять на работу всей сети;
- ограниченная длина кабеля и количество рабочих станций;
- трудно определить дефекты соединений
В сети построенной по топологии типа “звезда” каждая рабочая станция подсоединяется кабелем (витой парой) к концентратору или хабу (hub). Концентратор обеспечивает параллельное соединение ПК и, таким образом, все компьютеры, подключенные к сети, могут общаться друг с другом.
Данные от передающей станции сети передаются через хаб по всем линиям связи всем ПК. Информация поступает на все рабочие станции, но принимается только теми станциями, которым она предназначается. Так как передача сигналов в топологии физическая звезда является широковещательной, т.е. сигналы от ПК распространяются одновременно во все направления, то логическая топология данной локальной сети является логической шиной.
Данная топология применяется в локальных сетях с архитектурой 10Base-T Ethernet.
Преимущества сетей топологии звезда:
- легко подключить новый ПК;
- имеется возможность централизованного управления;
- сеть устойчива к неисправностям отдельных ПК и к разрывам соединения отдельных ПК.
Недостатки сетей топологии звезда:
- отказ хаба влияет на работу всей сети;
- большой расход кабеля;
В сети с топологией кольцо все узлы соединены каналами связи в неразрывное кольцо (необязательно окружность), по которому передаются данные. Выход одного ПК соединяется со входом другого ПК. Начав движение из одной точки, данные, в конечном счете, попадают на его начало. Данные в кольце всегда движутся в одном и том же направлении.
Принимающая рабочая станция распознает и получает только адресованное ей сообщение. В сети с топологией типа физическое кольцо используется маркерный доступ, который предоставляет станции право на использование кольца в определенном порядке. Логическая топология данной сети — логическое кольцо.
Данную сеть очень легко создавать и настраивать. К основному недостатку сетей топологии кольцо является то, что повреждение линии связи в одном месте или отказ ПК приводит к неработоспособности всей сети.
Как правило, в чистом виде топология “кольцо” не применяется из-за своей ненадёжности, поэтому на практике применяются различные модификации кольцевой топологии.
Топология Token Ring
Эта топология основана на топологии «физическое кольцо с подключением типа звезда». В данной топологии все рабочие станции подключаются к центральному концентратору (Token Ring) как в топологии физическая звезда. Центральный концентратор — это интеллектуальное устройство, которое с помощью перемычек обеспечивает последовательное соединение выхода одной станции со входом другой станции.
Другими словами с помощью концентратора каждая станция соединяется только с двумя другими станциями (предыдущей и последующей станциями). Таким образом, рабочие станции связаны петлей кабеля, по которой пакеты данных передаются от одной станции к другой и каждая станция ретранслирует эти посланные пакеты. В каждой рабочей станции имеется для этого приемо-передающее устройство, которое позволяет управлять прохождением данных в сети. Физически такая сеть построена по типу топологии “звезда”.
Концентратор создаёт первичное (основное) и резервное кольца. Если в основном кольце произойдёт обрыв, то его можно обойти, воспользовавшись резервным кольцом, так как используется четырёхжильный кабель. Отказ станции или обрыв линии связи рабочей станции не вличет за собой отказ сети как в топологии кольцо, потому что концентратор отключет неисправную станцию и замкнет кольцо передачи данных.
В архитектуре Token Ring маркер передаётся от узла к узлу по логическому кольцу, созданному центральным концентратором. Такая маркерная передача осуществляется в фиксированном направлении (направление движения маркера и пакетов данных представлено на рисунке стрелками синего цвета). Станция, обладающая маркером, может отправить данные другой станции.
Для передачи данных рабочие станции должны сначала дождаться прихода свободного маркера. В маркере содержится адрес станции, пославшей этот маркер, а также адрес той станции, которой он предназначается. После этого отправитель передает маркер следующей в сети станции для того, чтобы и та могла отправить свои данные.
Один из узлов сети (обычно для этого используется файл-сервер) создаёт маркер, который отправляется в кольцо сети. Такой узел выступает в качестве активного монитора, который следит за тем, чтобы маркер не был утерян или разрушен.
Преимущества сетей топологии Token Ring:
- топология обеспечивает равный доступ ко всем рабочим станциям;
- высокая надежность, так как сеть устойчива к неисправностям отдельных станций и к разрывам соединения отдельных станций.
Недостатки сетей топологии Token Ring: большой расход кабеля и соответственно дорогостоящая разводка линий связи.
Источник: studfile.net