Что такое компьютерная документация
Сборник компьютерной литературы, учебников, самоучителей по работе с программами. Разделы : 3D графика, анимация, графика, документация инженера, интернет, мультимедия, операционные системы, офис, программирование.
- 101 совет при работе с графикой
- 3D Studio MAX Изнутри
- Adobe Illustrator 8.0 или Corel DRAW 9.0
- FAQ по CorelDRAW
- Photoshop в примерах и задачах
- Xara 2.0 учебник
- Векторизуем отсканированный логотип
- ВСЕ ВОПРОСЫ ОТВЕТЫ ДЛЯ 3DS MAX
- Загибаем края в Photoshop
- Закругление углов в Photoshop
- Изучаем Adobe Illustrator
- Мануал Photoshop 7.0
- Ода 3D Studio MAX R3
- Пишем жидким металлом в Photoshop
- Пунктирная рамка в Photoshop
- Растровая графика Поединок форматов
- Рисуем в Photoshop CS 1
- Рисуем в Photoshop CS 2
- Рисуем в Photoshop CS 3
- Рисуем в Photoshop CS 4
- Сканирование изображений 2
- Создаем Сигарету в Photoshop
- Уроки 3ds max REACTOR
- Уроки 3ds max Сборка персонажа
- Уроки 3ds max Моделирование головы
- Уроки 3DStudio Max для начинающих
- Эффекты Photoshop 7.0
- Иллюстрированный самоучитель по 3DS MAX
- Иллюстрированный самоучитель по Adobe Illustrator
- Иллюстрированный самоучитель по Adobe Illustrator 9.0
- Иллюстрированный самоучитель по Adobe InDesign
- Иллюстрированный самоучитель по Adobe PageMaker
- Иллюстрированный самоучитель по Adobe Photoshop
- Иллюстрированный самоучитель по Adobe Photoshop 6
- Иллюстрированный самоучитель по CorelDraw
- Иллюстрированный самоучитель по Corel DRAW 11
- Иллюстрированный самоучитель по Flash MX
- Иллюстрированный самоучитель по InDesign
- Иллюстрированный самоучитель по Macromedia Flash
- Иллюстрированный самоучитель по Maya 4.5 для начинающих
- Иллюстрированный самоучитель по Maya 4.5 для продвинутых
- Иллюстрированный самоучитель по Publisher
- Иллюстрированный самоучитель по программам Adobe
- Иллюстрированный самоучитель по секретам работы с Photoshop 7 и Illustrator 10
- Иллюстрированный самоучитель по цифровой графике
- Иллюстрированный самоучитель по цифровой фотографии
- Коллекция документации
100 советов по Photoshop
Adobe Photoshop разработка собственных эффектов
Adobe Press Adobe Acrobat.5.0C
FAQ по Adobe Photoshop
LightWave 3D 8
New Riders Inside Maya 5
New Riders Quark Xpress 6
PhotoShop 5
PhotoShop Unlimited
Photoshop в примерах и задачах
Архитектура графических терминалов и рабочих станций
Графические файловые форматы
Захват изображения с помощью программы HyperSnap-DX
Золотое волшебство к Новому году
Кодирование изображений
Компьютерная графика и решаемые ею задачи
Настройка Photoshop 5.5
Разрешение и разрешающая способность
Старый друг лучше новых двух
Техника сканирования
Трюки и спецэффекты в PhotoShop 5.5
Трюки и спецэффекты в PhotoShop 6.0
Уроки и секреты PhotoShop
Уроки по Photoshop. Actions, Tutorial, Эффекты
Цветовые модели
Часто задаваемые вопросы и ответы на них по CorelDRAW
- AutoCAD Печать чертежей
- Системы электронного технического документооборота
- FAQ по Компас-График
- FAQ по технике CB-диапазона (антенны)
- FAQ по технике CB-диапазона (кто, где есть в мире СВ.)
- FAQ по технике CB-диапазона (общие вопросы)
- FAQ по технике CB-диапазона (радиослужбы в мире СВ.)
- MathCad 8.0 Pro 2
- Антенны спутниковые, КВ., УКВ, Си-Би, ТВ, РВ
- Введение в систему Mathmatica 3.0
- Выбери антенну сам
- Инструмент архитектора в информационную эпоху
- Лекции по САПР СТИЛИ ЛИНИЙ
- Лекции по САПР СТИЛИ ШТРИХОВОК
- Масштабы в AUTOCAD
- Программирование в среде САПР
- Работа в среде Autocad
- СПРАВОЧНИК ПО ЯЗЫКУ VHDL
- Статистика - Электронный учебник
- Телевизионные и спутниковые антенны
- Телеприем на дачном участке, далеко за городом
- Цифровое спутниковое телевидение FAQ
- Электроника для Дома
- Иллюстрированный самоучитель AutoCAD 2002
- Иллюстрированный самоучитель AutoCAD 2004
- Иллюстрированный самоучитель Autodesk Mechanical Desktop 2004
- Иллюстрированный самоучитель по ArchiCAD
- Иллюстрированный самоучитель по Maple
- Иллюстрированный самоучитель по Mathematica
- Иллюстрированный самоучитель по MatLab
- Иллюстрированный самоучитель по OrCAD
- Иллюстрированный самоучитель по P-cad
- Иллюстрированный самоучитель по SPSS
- Иллюстрированный самоучитель по созданию чертежей
- Иллюстрированный самоучитель по схемотехнике
- CSS (Каскадные таблицы стилей)
- ICQ 2000 Попробуем взлететь
- Macromedia Dreamweaver Справочник
- The Bat! и списки рассылки
- Документация по Html
- Инструментарий Html редактора
- Интернет и безопасность в нем
- Как получить нелегальный доступ в Интернет
- Каскадные Таблицы Стилей, уровень 2
- На Internet и суда нет
- О спецификации HTML 4.0
- Приемы верстки веб страниц
- Протоколы TCP IP Принципы, протоколы и архитектура
- Работа с графикой
- Расширяемый Язык Разметки (XML) 1.0
- Расширяемый Язык Таблиц Стилей (XSL)
- Руководство по глобальной компьютерной сети Internet
- Спецификация HTML 4.01
- Справочная информация по Html
- Цели дизайна Сайта
- Этика и нравственность в Internet
- Иллюстрированный самоучитель PHP
- Иллюстрированный самоучитель по Adobe Golive
- Иллюстрированный самоучитель по Dreamweaver MX
- Иллюстрированный самоучитель по Flash MX
- Иллюстрированный самоучитель по GPRS
- Иллюстрированный самоучитель по Macromedia Flash 5
- Иллюстрированный самоучитель по Macromedia HOMESITE
- Иллюстрированный самоучитель по WEB-графике
- Иллюстрированный самоучитель по анимации для Интернет
- Иллюстрированный самоучитель по ведению бизнеса в Интернет
- Иллюстрированный самоучитель по защите в Интернет
- Иллюстрированный самоучитель по разработке безопасности
- Иллюстрированный самоучитель по созданию сайтов
- Иллюстрированный самоучитель по электронной почте
- Иллюстрированный самоучитель по локальным сетям
- Иллюстрированный самоучитель по FrontPage 2002
- Иллюстрированный самоучитель по Microsoft Internet Explorer 6.0
- Коллекция документации
50 Fast Dreamweaver MX Techniques
Crime and the Internet
Dreamweaver MX 2004 in 10 Steps or Less
Dreamweaver MX 2004 The Missing Manual
FRONTPAGE 2003 INSIDE OUT
Macromedia Fireworks MX 2004 Fast and Easy Web Development
Macromedia Flash MX 2004 ActionScript
Macromedia FreeHand MX Training from the Source
Macromedia Studio MX 2004 All In One Desk Reference For Dummies
Show Me Microsoft Office FrontPage 2003
Special Edition Using MS Office Outlook 2003
Адреса Интернета
Введение и обзор TCP IP
Маршрутизация IP-дейтаграмм
Межсетевой протокол
Обзор базовых сетевых технологий
Организация шлюза из ЛВС в Интернет
Понятие межсетевого обмена и архитектурная модель
Принципы построения составных сетей
Протокол IPv.6
Протокол TCP
Разделение протоколов на уровни
Руководство по TCP
Семейство протоколов TCP IP
- CUBASE VST Практическое руководство
- DivX особенности сжатия видео в домашних условиях
- FAQ Домашняя MIDI-студия
- Make Music Home
- MPEG-Вопросы и ответы
- MPEG - Общая информация
- Ulead MediaStudio Pro 7 Инструкция по применению
- Ulead MediaStudio Pro 7 Инструкция по применению 2
- Аудио MPEG, аудио не MPEG и не аудио MPEG
- Видеоклип - своими руками
- Воспроизведение видео на компьютере
- Домашняя студия звукозаписи Мастеринг
- Запись и редактирование звукового файла
- Захват, обработка и хранение видео с использованием ПК
- Как переписать домашний видеофильм на компакт-диск
- Как сделать видеофильм на компьютере
- Копированию DVD дисков
- Многоканальный звук в любительском фильме
- Настройки XviD кодека
- Немузыкальная часть музыкальных файлов
- Озвучиваем видеофильм сами
- Популярно о MIDI
- Практические советы по работе с цифровым видео
- Работа с программой Cakewalk
- Руководство для начинающих по копированию фильмов с DVD дисков
- Сжатие видео при помощи WMV
- Создаем DVD со звуком 5.1!
- Создание музыки дома
- Такой разный звук
- УЧЕБНИК ПО CUBASE
- Фильм с фотокамеры
- Что такое двухпотоковое цифровое редактирование
- Иллюстрированный самоучитель по CD, DVD
- Иллюстрированный самоучитель по CubaseSX
- Иллюстрированный самоучитель по SoundForge
- Иллюстрированный самоучитель по виртуальному звуку
- Иллюстрированный самоучитель по записи лазерных дисков
- Иллюстрированный самоучитель по компьютерной графике и звуку
- Иллюстрированный самоучитель по основам компьютерной музыки
- Иллюстрированный самоучитель по созданию домашнего видеофильма
- 64-разрядная система Windows XP
- FAQ Windows XP 3
- FreeBSD глазами администратора
- FreeBSD Руководство пользователя
- NT club Консоль
- Windows Millenium FAQ
- Windows Server 2003 достижения и тенденции
- Windows Server 2003 подробности
- Windows XP FAQ 1
- Windows XP FAQ 2
- Автоматизация установки и оптимизация ОС Windows ХР.
- Ваш билет до Windows 2000
- Ваш собственный сервер установка Windows Server 2003
- Внутри Windows Management Interface
- Групповые политики в Windows2000 Server
- Документация по реестру Windows
- Настройка сервисов в Windows2000 XP 2003
- Описание служб в Windows NT2000XP
- Основные команды консоли восстановления
- Работаем с реестром Windows NT
- Разгоняем Windows 98
- Руководство по настройке Windows 2003
- Руководство по настройке Windows 2003 Server как рабочей станции
- Руководство по настройке Windows2000 XP 2003
- Система FAT32 и разделы на диске
- Служба каталогов Active Directory в Windows 2000 Server
- Советы по компьютеру
- Ставим LONGHORN PDC build 4051
- Третья версия WinXP FAQ CHM Edition
- Иллюстрированный самоучитель по Windows 2000
- Иллюстрированный самоучитель по Windows XP
- Дистрибутивы и общие вопросы по Linux
- Иллюстрированный самоучитель по Linux
- Иллюстрированный самоучитель по настройке и оптимизации компьютера
- Иллюстрированный самоучитель по теории операционных систем
- Мультимедиа в Linux
- Настройка и работа в Linux
- Операционная система Linux
- Программирование в Linux
- Редактирование текста в Linux
- Коллекция документации
Addison Wesley Moving To Linux Kiss The Blue Screen Of Death Goodbye
Addison Wesley UNIX Network Programming
Apache & Linux
DriveSpace FAQ
Explorer FAQ
Internet в Linux
John Wiley And Sons Mastering Unix Shell Scripting
Linux HowTo
Mac Osx Guide
Mandrake Linux 9.0
Manning Publications Company Programming Guide for Unix Developers
Microsoft Windows Server 2003 Terminal Services
Microsoft Windows Xp Fast and Easy Media Center Edition
No Starch Press Absolute OpenBSD UNIX For The Practical Paranoid
Prentice Unix Systems Programming Communication Concurrency And Threads
Que Show Me Microsoft Windows XP
Red Hat Linux 7.3
Red Hat Linux 8.0
Sybex Linux Power Tools
The MIT Press Beowulf Cluster Computing With Linux Second
Win2000 FAQ
Windows 2000 - поговорим о производительности
Windows 2000 на домашнем компьютере
Windows Help Guide (Вопросы о Windows)- Версия1.5
Windows Shel.Script.Programming.for.the.Absolute.Beginner.eBook-DDU
Windows XP In 10 Steps
Windows XP Professional Administrators Guide
X Window
Администрирование дисков в Windows 2000
Безопасность Linux
Вариации на тему двойной загрузки
Вопросы о Windows
Все что нужно для нормальной работы Windows
Выбор и установка дистрибутива Linux
Если компьютер заболел
Изменение LOGIN PASSWORD под WINNT
Лицензирование в Linux
Написание драйверов для Windows NT 4.0
Особенности файловой системы NTFS
Офис в Linux
Первое знакомство c NT
Подключаем второй монитор в Windows98
Подробно о FAT
Программирование в Linux
Программы для тестирования компьютера
Работа администратора с user account
Руководство FreeBSD
Сетевые средства Линукса
Сети в Linux
Советы и описание реестра Windows
Тонкая настройка Windows Me
Чистим реестр
- Узелки на память при работе с MS Office
- Access FAQ Рекомендации
- Access Первые шаги
- FAQ по настройке StarOffice 5.2 в среде Black Cat Linux 6.2
- FAQ по паролям в MS Office
- FAQ по русификации StarOffice 5.1a
- MS Word Выделение текста
- Outlook Express FAQ
- Вставка объектов Текстовые эффекты в MS Word
- Вывод документа на печать в MS Word
- Знакомство с Word
- Использование полей в MS Word
- Как проводить вычисления в Microsoft Excel
- Макрос макросом вышибают
- Несколько советов по OpenOffice
- Офисные правила Интернет решения
- Офисные правила основы редактирования
- Офисные правила Печать
- Офисные правила полезные мелочи
- Офисные правила простое решение сложных проблем
- Офисные правила простое решение сложных проблем 1
- Офисные правила простое решение сложных проблем 3
- Офисные правила работа с макросами
- Офисные правила работа с таблицами
- Письмовник составление и перевод деловых документов
- Почему Word'97 печатает квадратики вместо русских букв
- Работа с Microsoft Excel в IIS 4.0
- Работаем с текстовыми процессорами
- Скрытые команды Word
- Снова о секретах MS Word
- Создание таблиц в Word
- Текстовые редакторы в Linux
- Форматирование абзацев и текста в Word
- Иллюстрированный самоучитель по Access
- Иллюстрированный самоучитель по Excel
- Иллюстрированный самоучитель по FrontPage 2002
- Иллюстрированный самоучитель по Microsoft Internet Explorer
- Иллюстрированный самоучитель по Office XP
- Иллюстрированный самоучитель по Outlook
- Иллюстрированный самоучитель по документообороту
- Иллюстрированный самоучитель по офисной работе с документами
- 10h советов программисту на TP
- 87 Хитростей и трюков для Visual Basica
- Borland C++ Builder FAQ
- FAQ по СОРТИРОВКАМ версия 1_1
- GDI графика в Delphi
- Visual C++ для Начинающих
- Выделение ресурса есть инициализация
- Графика в Delphi
- Документация по Win API
- Как поместить битмап в List-ComboBox
- Как сделать стандартные цвета в Delphi светлее или темнее
- Обратная польская запись
- Оптимизация программ на ассемблере
- Перетасовка экрана в Delphi
- Пишем Screensaver в Delphi
- Программирование на основе Win32 API в Delphi
- Работа с реестром в Delphi
- Реализация обработки событий на C++
- Секреты Delphi Как отключить монитор
- Создание динамических массивов
- Создание сервисов для Windows NT
- Создание трехуровневого приложения
- Создание элементов управления ActiveX с помощью C++Builder
- Справочник Borland C++
- Иллюстрированный самоучитель PHP
- Иллюстрированный самоучитель по Assembler
- Иллюстрированный самоучитель по Delphi 6
- Иллюстрированный самоучитель по Delphi 7 для начинающих
- Иллюстрированный самоучитель по Delphi 7 для профессионалов
- Иллюстрированный самоучитель по Java
- Иллюстрированный самоучитель по Perl
- Иллюстрированный самоучитель по SQL-сервер в Linux
- Иллюстрированный самоучитель по SVGA
- Иллюстрированный самоучитель по Tirbo Pascal
- Иллюстрированный самоучитель по Visual Basic 6.0
- Иллюстрированный самоучитель по Visual Foxpro 7
- Иллюстрированный самоучитель по Ассемблеру
- Иллюстрированный самоучитель по задачам и примерам Assembler
- Иллюстрированный самоучитель по практике программирования
- Иллюстрированный самоучитель по программированию систем безопасности
- Иллюстрированный самоучитель по теории операционных систем
- Иллюстрированный самоучитель по Турбо Паскалю
- Иллюстрированный самоучитель по экспертным системам
С выбором конечного формата обычно проблем не возникает, так как целевая операционная система предъявляет свои требования. Так, например, для программ для Windows — это формат скомпилированной справки CHM, для Linux и BSD систем — это man. Общим для всех систем форматом для онлайн справки является html, а для печати — pdf.
Ситуация осложняется в случае, если необходимо иметь документацию в нескольких форматах — для распространения с программой (chm или man), для размещения на сайте (html) и для печати (pdf). При этом возможно, что содержание документации в различных форматах может несколько отличаться. Например, видеофрагменты имеет смысл включать в онлайн документацию, а в печатной версии их нужно заменять на статическое изображение, возможно дополненным qrcode ссылки на видеофрагмент. Кроме того, содержание документов может отличаться и для различных категорий пользователей, версий, комплектов поставки и других факторов.
1.2. Исходные форматы
Несмотря на кажущуюся очевидность необходимости использования специально созданных программ, здесь не все так однозначно.
В зависимости от целевой операционной системы подходы отличаются.
1.2.1. Проприетарные исходные форматы
Так, для создания скомпилированной справки для Windows в формате chm Microsoft предлагает использовать специальный бесплатный компилятор HTML Help Workshop. При этом исходные тексты должны быть подготовлены в формате html (редактор в поставку не входит), а файлы оглавления — в специфическом формате. Никаких средств формирования печатных руководств не предоставляется.
Разумеется, специализированные программы для создания справки (Robohelp, Help&Manual, HelpScribble и им подобные) предоставляют высокий уровень сервиса, обладают возможностью формирования выходных документов в различных форматах и даже в некоторой степени профилировать содержимое.
Однако им присущи следующие недостатки:
- Во-первых, все эти системы коммерческие и лицензируются по количеству используемых рабочих мест.
- Во-вторых, используемый ими внутренний формат является проприетарным и не поддержимается никаким ПО, кроме продаваемого. Возможность импортировать файлы в проект вам, конечно, будет предоставлена, а вот экспортировать проект в какой либо открытый формат, пригодный для дальнейшей обработки, не удастся. Даже в случае использования в качестве внутреннего формата XML (как, например, Help&Manual) схема его остается закрытой и никак не задокументированной.
- В-третьих, возможности по изменению внешнего вида выходного документа являются недостаточными для формирования, например, документации в соответствиями с требованиями ГОСТ.
- В-четвертых, с этими программами организовать коллективную работу если и возможно, то крайне затруднительно
На сегодняшний день таких форматов несколько:
-
, используемый дефакто в Linux (BSD) системах; , применяемый в различного рода энциклопедиях и даже давший им общее название; — так сказать, «многоцелевой» формат документирования.
Все эти разметки используют некоторый символьный нетеговый набор правил оформления заголовок, иллюстраций и ссылок, предполагающий редактирование в простых текстовых редакторах. Подготовка же пригодного к просмотру вида осуществляется программно как правило на стороне сервера.
1.3. Редакторы
Несмотря на то, что для создания и редактирования исходных текстов достаточно возможностей блокнота, некоторые сервисные функции, такие как проверка правописания и подсветка разметки были бы писателю весьма кстати.
Одним из таких редакторов является MarkdownPad.
1.3.1. MarkdownPad
Рисунок 1. Редактор MarkdownPad 2
Как видно из копии экрана, редактор MarkdownPad 2 поддерживает «живой» предварительный просмотр редактируемого файла с поддержкой синхронной прокрутки исходного текста и результата рендеринга.
При установке на Windows 8 может возникнуть ситуация, когда предварительный просмотр недоступен.
Редактор поддерживает подсветку синтаксиса, проверку синтаксиса одного языка (в том числе русского), экспорт в форматы 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 формат можно выполнить следующей командой:
Результатом будет готовый html-файл:
Рисунок 6. HTML-документ, сформированный из Markdown утилитой pandoc
За свою универсальность программа образно названа автором «швейцарским армейским ножом».
Действительно, pandoc справляется с конвертированием без каких-либо потерь информации. При конвертировании из формата MarkDown поддерживается чтение трех параметров метаданных — заголовка, автора и даты документа. Поддерживается также передача параметров командной строки для установки некоторых специфических свойств, например языка документа. Есть возможность задать свой шаблон выходного документа, до некоторой степени видоизменяя его.
Так, например, в приведенном выше примере подразумевается, что в текущей папке есть файл h.html, который играет роль заголовка. Если в этом файле добавить ссылку на стилевой файл и, определив <base target="_blank"> , получим следующий результат:
Рисунок 7. HTML-документ, сформированный pandoc с использованием заголовочного файла со ссылками на стили
Как видно из примера, заголовки приобрели свой стиль, а внешние ссылки стали открываться в новой вкладке браузера.
Вышеописанные возможности формата делают оправданным использования разметки Markdown для документирования относительно небольших программных систем, к оформлению которых не предъявляется требований ГОСТ, что и доказывается ее широким использованием в системе Git.
Что же касается больших систем с обширной и сложной документацией, то для ее создания видится применение системы единого источника Docbook. Могут иметь место и переходные случаи, когда масштаб проект проявляется не сразу.
1.6. Docbook
Сложность создания исходных XML-источников можно преодолеть путем использования исходных текстов в формате Markdown с последующим их конвертированием в Docbook. Такое преобразование поддерживается утилитой pandoc. Так, команда
Использование заголовочного файла h.xml (можно просто пустого) необходимо для корректной обработки метатегов и формирования статьи.
Рисунок 8. Сформированная статья в XML-редакторе
Следует отметить несколько дополнительных требований к разметки markdown, которая будет использована для преобразования в docbook:
Во-первых, следует избегать использования в тексте символов угловых скобок (< и >), так как в XML они используются для выделения тегов, а конвертер оставляет их как есть. Если же угловые скобки нужны по смыслу, то следует использовать сущности < и > .
Во-вторых, при вставке рисунка обязательно вводить альтернативный текст, так как pandoc использует его для создания обязательного тега title у тега figure .
Однако выходной текст формируется в устаревшем формате Docbook 4 версии, в то время как современная 5 версия предоставляет существенно более богатые возможности по семантической разметке.
Для преобразования текста из 4 в 5 версию можно воспользоваться специальным преобразованием db4-upgrade.xsl, входящим в комплект поставки Docbook.
Полученный таким образом xml файл схемы docbook 5 можно использовать при формировании единого источника.
Рисунок 9. Cтатья схемы в XML-редакторе в режиме автора
Описанная цепочка преобразований может показаться на первый взгляд длинной и неоправданно сложной. Однако освоив один раз необходимые инструменты и разработав для часто выполняемых задач командные файлы (скрипты) можно сэкономить значительное количество времени в дальнейшем.
Следует особо подчеркнуть, что технология единого источника обладает ярко выраженным кумулятивным эффектом. Начальные временные затраты на разработку типовых неоднократно используемых фрагментов текста окупаются при их использовании в последующих проектах. Именно это качество делает особо привлекательным технологию единого источника при документировании серийных программных систем.
Набор преобразований Docbook поддерживает формирование документов в HTML со стилями, PDF для печати так сказать «из коробки».
Внешний вид выходных документов может быть до определенной степени настроен с помощью параметров. Полученные файл формата FO-XSL pandoc5.fo является промежуточным и нужен для построения конечного PDF.
Немаловажна и возможность автоматического формирования оглавления, списка иллюстраций, листингов, таблиц, индексного указателя, глоссария терминов и списка литературы.
При большом количестве документов в составе пакета также возможно создание отдельного списка с возможностью автоматического формирования правильно оформленных ссылок на них. В случае же подготовки типографского макета руководства с учетом особых требований, например ГОСТ, необходимо разработать дополнительные xsl для форматов обычных страниц, титульной и финальной страницы.
Документ — элемент документации: целевая информация, предназначенная для конкретной аудитории, размещенная на конкретном носителе (например, в книге, на диске, в краткой справочной карте) в заданном формате [1] .
Программный документ — документ, содержащий в зависимости от назначения данные, необходимые для разработки, производства, эксплуатации, сопровождения программы или программного средства [2] .
Содержание
Типы документации
Существует четыре основных типа документации на ПО:
Архитектурная/проектная документация
Проектная документация обычно описывает продукт в общих чертах. Не описывая того, как что-либо будет использоваться, она скорее отвечает на вопрос «почему именно так?» Например, в проектном документе программист может описать обоснование того, почему структуры данных организованы именно таким образом. Описываются причины, почему какой-либо класс сконструирован определённым образом, выделяются паттерны, в некоторых случаях даже даются идеи как можно будет выполнить улучшения в дальнейшем. Ничего из этого не входит в техническую или пользовательскую документацию, но всё это действительно важно для проекта.
Техническая документация
При создании программы, одного лишь кода, как правило, недостаточно. Должен быть предоставлен некоторый текст, описывающий различные аспекты того, что именно делает код. Такая документация часто включается непосредственно в исходный код или предоставляется вместе с ним.
Подобная документация имеет сильно выраженный технический характер и в основном используется для определения и описания API, структур данных и алгоритмов.
Использование генераторов документации и документирующих комментариев многими программистами признаётся удобным средством, по различным причинам. В частности, при таком подходе документация является частью исходного кода, и одни и те же инструменты могут использоваться для сборки программы и одновременной сборки документации к ней. Это также упрощает поддержку документации в актуальном состоянии.
Пользовательская документация
В отличие от технической документации, сфокусированной на коде и том, как он работает, пользовательская документация описывает лишь то, как использовать программу.
В случае если продуктом является программная библиотека, пользовательская документация и документация на код становятся очень близкими, почти эквивалентными понятиями. Но в общем случае, это не так.
Обычно, пользовательская документация представляет собой руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет инструкции о том что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение.
Маркетинговая документация
Для многих приложений необходимо располагать рядом рекламные материалы, с тем чтобы заинтересовать людей, обратив их внимание на продукт. Такая форма документации имеет целью:
- подогреть интерес к продукту у потенциальных пользователей
- информировать их о том, что именно делает продукт, с тем чтобы их ожидания совпадали с тем, что они получат
- объяснить положение продукта по сравнению с конкурирующими решениями
Часто бывает так, что коробка продукта и другие маркетинговые материалы дают более ясную картину о возможностях и способах использования программы, чем всё остальное.
Примечания
- ↑ 12 ГОСТ Р ИСО/МЭК 15910-2002 — Процесс создания документации пользователя программного средства
- ↑ГОСТ 19781—90 Единая система программной документации. Обеспечение систем обработки информации программное
См. также
Ссылки
Кент Бек • Гради Буч • Фред Брукс • Barry Boehm • Уорд Каннингем • Оле-Йохан Даль • Том Демарко • Эдсгер Вибе Дейкстра • Дональд Кнут • Мартин Фаулер • Чарльз Энтони Ричард Хоар • Watts Humphrey • Майкл Джексон • Ивар Якобсон • Craig Larman • James Martin • Мейер Бертран • Дэвид Парнас • Winston W. Royce • James Rumbaugh • Никлаус Вирт • Эдвард Йордан • Стив Макконнелл
Моделирование данных • Архитектура ПО • Функциональная спецификация • Язык моделирования • Парадигма • Методология • Процесс разработки • Качество • Обеспечение качества • Структурный анализ)
CMM • CMMI • Данных • Function model • IDEF • Информационная • Metamodeling • Object model • View model • UML
- Техническая документация
- Программное обеспечение
- Разработка программного обеспечения
Wikimedia Foundation . 2010 .
Полезное
Смотреть что такое "Документация на программное обеспечение" в других словарях:
Программное обеспечение — Запрос «Software» перенаправляется сюда; см. также другие значения … Википедия
ПРОГРАММНОЕ СРЕДСТВО — 6. ПРОГРАММНОЕ СРЕДСТВО по ГОСТ 28806 90. Источник: РБ 004 98: Требования к сертификации управляющих систем, важных для безопасности атомных станций … Словарь-справочник терминов нормативно-технической документации
обеспечение — Процесс скоординированного управления по обеспечению всех материалов и ресурсов, требуемых для эксплуатации изделия. Источник: ГОСТ Р 53480 2009: Надежность в технике. Термины и определения оригинал документа … Словарь-справочник терминов нормативно-технической документации
Canon EOS 30D — Тип цифровой зеркальный фотоаппарат Матрица КМОП 22,5 × 15,0 мм (Kf = 1,6) … Википедия
Canon EOS 600D — Canon EOS Digital Rebel T3i Canon EOS Kiss X5 Тип DSLR … Википедия
В процессе своей деятельности хозяйствующие субъекты все реже отдают предпочтение бумажным носителям. Система электронного документооборота – это передовой стандарт, уже активно используемый в США и Европе, а у нас только набирающий популярность. Но какой она может быть и что за возможности дает? Предлагаем рассмотреть эти и другие сопутствующие моменты.
Сегодня она – обязательная и ключевая часть IT-инфраструктуры современного предприятия. Она существенно повышает эффективность деятельности – как коммерческой, так и промышленной или государственной организации, – помогая удобнее, быстрее, правильнее решать задачи как внутреннего управления, так и внешнего взаимодействия (с межведомственными подразделениями, вышестоящими инстанциями, поставщиками, целевой аудиторией).
Что такое система электронного документооборота (СЭД)
Она представляет собой совокупность программ, обеспечивающих создание, редактирование, разграничение прав доступа и распространение файлов в компьютерных сетях с сохранением возможностей контроля над ними на уровне компании.
Для ее внедрения требуется покупать платформу – программный пакет – и аппаратные средства для ее установки (сервер, сетевое оборудование и тому подобное). Для ее использования на уровне двух организаций и более нужен оператор, который будет контролировать отправку и доставку, правильность формата, заверение подписей, сохранность архива.
Разберемся с сокращениями, чтобы вы понимали, что такое СЭД, САД и так далее; первая аббревиатура общепринятая, тогда как под второй скрывается автоматизация делопроизводства; не реже можно встретить СЭДО и САДО, означающие системы документооборота – обычного и автоматизированного соответственно.
История развития
1. 80е годы ХХ века – стали появляться разрозненные решения, на базе отдельно взятых предприятий, разработанные под их нужды, силами их же внутренних специалистов; хорошо интегрировались в уже созданную инфраструктуру компании, но оставались плохо масштабируемыми – их практические нельзя было изменить.
2. Середина 90х – создание первых универсальных СЭД с возможностью адаптации к потребностям самых разных заказчиков; внедрялись уже сторонними разработчиками, в две стадии: сначала писалось унифицированное ядро, которое после подгонялось под конкретную фирму.
3. Старт нулевых – переориентация на WorkFlow и популяризация процессно-ориентированных движков; это позволило качественно изменить подход и не просто переводить бумажные документы в электронный вид, но и начать эффективно управлять их оборотом, постепенно его оптимизируя.
4. С 2005 года – появление и повсеместное распространение принципа enterprise content management (ECM), позволившего улучшить методологию и ввести разделение на файл и контент; вслед за этим двухзвенная архитектура эволюционировала в трехзвенную – вместо связи «СУБД – приложение» появился треугольник «СУБД – сервер – интерфейс», что позволило устранить многие ошибки.
Сегодня наблюдаются благотворные условия для дальнейшего совершенствования решений и предоставления бизнесу, промышленным предприятиям и государственным структурам все более мощных и удобных инструментов.
Читайте также: