Что такое руководство системного администратора

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

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

Составление документации для пользователей имеет свои особенности, связанные с тем, что пользователь, как правило, не является профессионалом в области разработки программного обеспечения. В книге С. Дж. Гримм [17] даны рекомендации по написанию подобной программной документации:

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

•излагайте ясно, используйте короткие предложения;

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

•будьте точны и рациональны – длинные и запутанные руководства обычно никто не читает, например, лучше привести рисунок формы, чем долго ее описывать.

Руководство пользователя, как правило, содержит следующие разделы:

•общие сведения о программном продукте;

•описание установки;

•описание запуска;

•инструкции по работе (или описание пользовательского интерфейса);

•сообщения пользователю.

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

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

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

Раздел Инструкции по работе обычно содержит описание режимов работы, форматов ввода-вывода информации и возможных настроек.

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

11.4. Руководство системного программиста

По ГОСТ 19.503–79 руководство системного программиста должно содержать всю информацию, необходимую для установки программного обеспечения, его настройки и проверки работоспособности. Кроме того, как указывалось выше, в него часто включают и описание необходимого обслуживания, которое раньше приводилось в руководстве оператора (ГОСТ 19.505–79) и/или руководстве по техническому обслуживанию (ГОСТ 19.508–79). В настоящее время данную схему используют для составления руководства системному администратору.

Руководство системного программиста должно содержать следующие разделы:

•общие сведения о программном продукте,

•структура,

•настройка,

•проверка,

•дополнительные возможности,

•сообщения системному программисту.

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

ипараметрам внешних устройств, требования к программному обеспечению и т. п.).

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

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

Вразделе Проверка программы должно быть приведено описание способов проверки работоспособности программы, например контрольные примеры.

Вразделе Дополнительные возможности должно быть приведено описание дополнительных возможностей программы и способов доступа к ним.

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

11.5. Основные правила оформления программной документации

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

Оформление текстового и графического материала. Текстовые документы оформляют на листах формата А4, причем графический материал допускается представлять на листах формата A3. Поля на листе определяют в соответствии с общими требованиями: левое – не менее 30, правое – не менее 10, верхнее – не менее 15, а нижнее – не менее 20 мм. В текстовых редакторах для оформления записки параметры страницы заказывают в зависимости от устройства печати. При ручном оформлении документов параметры страницы выбирают из соображений удобства.

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

Наименование разделов пишут прописными буквами в середине строки. Расстояние между заголовками и текстом, а также между заголовками раздела и подразделов должно быть равно:

•при выполнении документа машинописным способом – двум интервалам;

•при выполнении рукописным способом – 10 мм;

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

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

•при выполнении документа машинописным способом – трем интервалам;

•при выполнении рукописным способом – не менее 15 мм;

•при использовании текстовых редакторов – определяется возможностями редактора. Разделы и подразделы нумеруются арабскими цифрами с точкой. Разделы должны

иметь порядковые номера 1, 2, и т. д. Номер подраздела включает номер раздела и порядковый номер подраздела, входящего в данный раздел, разделенные точкой. Например: 2.1, 3.5. Ссылки на пункты, разделы и подразделы указывают, используя порядковый номер раздела или пункта, например, «в разд. 4», «в п. 3.3.4».

Текст разделов печатают через 1,5-2 интервала. При использовании текстовых редакторов высота букв и цифр должна быть не менее 1,8 мм (шрифты № 11-12).

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

Оформление рисунков, схем алгоритмов, таблиц и формул. В соответствии с ГОСТ 2.105–79 «Общие требования к текстовым документам» иллюстрации (графики, схемы, диаграммы) могут быть приведены как в основном тексте, так и в приложении. Все иллюстрации именуют рисунками. Все рисунки, таблицы и формулы нумеруют арабскими цифрами последовательно (сквозная нумерация) или в пределах раздела (относительная нумерация). В приложении – в пределах приложения.

Каждый рисунок должен иметь подрисуночную подпись – название, помещаемую под рисунком, например:

Рис.12. Форма окна основного меню

На все рисунки, таблицы и формулы в записке должны быть ссылки в виде: «(рис. 12)» или «форма окна основного меню приведена на рис. 12».

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

Если рисунок занимает более одной страницы, на всех страницах, кроме первой, проставляется номер рисунка и слово «Продолжение». Например:

Рис. 12. Продолжение

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

Схемы алгоритмов должны быть выполнены в соответствии со стандартом ЕСПД. Толщина сплошной линии при вычерчивании схем алгоритмов должна составлять от 0,6…1,5 мм. Надписи на схемах должны быть выполнены чертежным шрифтом, высота букв и цифр должна быть не менее 3,5 мм.

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

Ссылки на таблицы в тексте пояснительной записки указывают в виде слова «табл.» и номера таблицы. Например:

Результаты тестов приведены в табл. 4.

Номер формулы ставится с правой стороны страницы в круглых скобках на уровне формулы. Например:

Ссылка на номер формулы дается в скобках. Например: «расчет значений проводится по формуле (12)».

Оформление приложений. Каждое приложение должно начинаться с новой страницы с указанием в правом углу слова «ПРИЛОЖЕНИЕ» прописными буквами и иметь тематический заголовок. При наличии более одного приложения все они нумеруются арабскими цифрами: ПРИЛОЖЕНИЕ 1, ПРИЛОЖЕНИЕ 2 и т. д. Например:

ПРИЛОЖЕНИЕ 2

Титульный лист расчетно–пояснительной записки

Рисунки и таблицы, помещаемые в приложении, нумеруют арабскими цифрами в пределах каждого приложения с добавлением буквы «П». Например:

Рис. П. 12 – 12-й рисунок приложения; Рис. П1.2 – 2-й рисунок 1-го приложения.

Если в приложении приводится текст программы, то каждый файл оформляют как рисунок с наименованием файла и его назначением, например:

Рис. П2.4. Файл menuran.pas – программа движения курсора основного меню.

Оформление списка литературы. Список литературы должен включать все использованные источники. Сведения о книгах (монографиях, учебниках, пособиях, справочниках и т. д.) должны содержать: фамилию и инициалы автора, заглавие книги, место издания, издательство, год издания. При наличии трех и более авторов допускается указывать фамилию и инициалы только первого из них со словами «и др.». Издательство надо приводить полностью в именительном падеже: допускается сокращение названия только двух городов: Москва (М.) и Санкт–Петербург (СПб.).

Сведения о статье из периодического издания должны включать: фамилию и инициалы автора, наименование статьи, издания (журнала), серии (ес-