webdonsk.ruКак сделать руководство программиста
Добавил пользователь Алексей Ф. Обновлено: 29.08.2024
(по ГОСТ 19.504-79. ЕСПД. Руководство программиста. Требования к содержанию и оформлению)
- Лист утверждения
- Титульный лист
- Аннотация
- Содержание
- Основная часть
- Назначение и условия применения программ
- Назначение программы
- Функции, выполняемые программой
- Условия, необходимые для выполнения программы
- Объем оперативной памяти
- Требования к составу периферийных устройств
- Требования к параметрам периферийных устройств
- Требования к программного обеспечению
- Требования к персоналу (программисту)
- Описание основных характеристик программы
- Временные характеристики программы
- Режим работы программы
- Средства контроля правильности выполнения программы
- Описание основных особенностей программы
- Самовосстанавливаемость программы
- Загрузка и запуск программы
Сайт оптимизирован для экранного разрешения 800х600
и браузера Inernet Explorer.![]()
Евгений Кучерявый
Пишет о разработке сайтов, в свободное время создает игры. Мечтает открыть свою студию и выпускать ламповые RPG.
Содержание
Правила хорошего тона в составлении документации
Составляя документацию, стоит следовать определенным правилам — они помогают сделать ее более понятной.
1. Документация нужна не всегда
Если программа одноразовая, не стоит тратить время на написание пояснений. Например, если нужен небольшой скрипт, который будет написан за пять минут и использован 1-2 раза.
2. Документация нужна не везде
Также не нужно писать пояснения ко всему. Если код написан хорошо, то по названиям уже будет понятно, что это такое и зачем оно используется. Например, легко догадаться, что метод int Sum (int a, int b) возвращает результат сложения двух чисел.
Исключение можно сделать, если речь идет об API или фреймворке, которыми пользуются многие разработчики: они не всегда видят исходный код, но могут использовать классы и методы. Поэтому им важно иметь список доступных методов. В этом случае задокументировать всё нужно просто для галочки.
3. Документация должна быть точной
Очень важно уметь ясно выражать свои мысли. Нужно предельно точно описывать, что делает тот или иной фрагмент кода. Для этого стоит давать как можно более короткие определения. Например:
В этом фрагменте кода объем документации к классу и его свойству не превышает одного предложения. Этого достаточно, чтобы было понятно, что это такое и для чего его нужно использовать.
4. Документация должна быть сухой
Хотя канцеляризмов нужно избегать, писать надо максимально сухо и по делу. Никаких стихов, метафор, аналогий или шуток — всё это может быть забавным, но не добавляет ясности.
5. В документации не должно быть старого кода
Этот правило больше касается обычных комментариев, чем самой документации. Однако оно очень важное, поэтому приведено здесь.
Никогда не храните в коде старые методы и операторы, даже если они задокументированы. Если что-то не используется в текущий момент — это мусор, от которого нужно избавиться.
Если есть сомнения пригодится ли еще этот код, его лучше сохранить в системе контроля версий — именно для этого ее и придумали.
Вариантов много. Например, можно сделать это в Word или Google Docs, тогда разработчики смогут скачивать файл из интернета. Некоторые хранят инструкции в печатном виде, но это плохой вариант, потому что документация быстро устаревает.
Лучший способ — писать всё прямо в коде программы. Тогда у каждого разработчика будет доступ к документации в любое время. Самый примитивный вариант — использовать комментарии.
Существует множество видов предоставления справочной информации пользователю – это и FAQ (frequently asked questions, часто задаваемые вопросы) и онлайн справка и руководство пользователя (user guide) и популярные сегодня подсказки (coachmarks, см. пример ниже), обучающие видео и другие.
![]()
Существуют разные причины, по которым требуется написать руководство пользователя системы. Начиная с просьб заказчика (в моей практике был случай, когда заказчику надо было поставлять руководство пользователя после каждой итерации, чтобы с его помощью он смог бы провести приемочное тестирование функциональности итерации) и заканчивая условиями контракта, касающимися поставки готового ПО, если говорить о разработке ПО на заказ. В случае разработки собственного продукта написание руководства пользователя тоже часто имеет место.
К созданию руководства часто привлекают аналитика, если нет возможности поручить техническому писателю. В подавляющем большинстве случаев самыми полными знаниями о системе обладает именно аналитик, он же обладает умением ясно излагать свои мысли в письменной форме в силу специфики профессии. Поэтому, мне не однократно приходилось сталкиваться с созданием руководств пользователя.
Ниже я приведу несколько практик для составления хорошего руководства пользователя. Часть из них, возможно, кому-то будут полезны и при написании спецификаций требований.
1. Стандарты
Часто бывает нужно написать документ, который бы удовлетворял требованиям действующих стандартов. Это могут быть:
Если потребности проекта позволяют вам не следовать жестким стандартам, в любом случае изучение этих документов может послужить стартовой точкой для написания качественного документа.
Также может оказаться полезной книга Юрия Кагарлицкого MetaGuide. Руководство для разработчиков технической документации к программному обеспечению.
2. Структура
Хорошо продумайте структуру документа: она должна покрывать все функциональные возможности системы, быть полной и понятной.
Хорошее руководство пользователя должно содержать:
- Аннотацию, в которой приводится краткое изложение содержимого документа и его назначение. Также рекомендуется писать краткую аннотацию в начале каждого крупного раздела.
- Введение, содержащее информацию о том, как лучше всего использовать данное руководство
- Содержание
- Главы, описывающие, как использовать ПО
- Глоссарий и
- Предметный указатель
Также руководство пользователя может содержать:
- FAQ и ответы на них
- Ссылки на дополнительную информацию по системе
- Раздел, описывающий возможные проблемы и пути их решения
Все главы и пункты, а также рисунки и таблицы лучше нумеровать, чтобы на них можно было сослаться внутри этого документа или из другого документа.
3. Пользователи
Подумайте о типичных пользователях данного ПО: необходимо, чтобы документ помогал им решать их насущные задачи.
Возможно, даже имеет смысл сделать разные разделы (или даже разные документы) для разных групп пользователей, если их взаимодействие с системой будет кардинально различаться. Например, администраторов системы (людей, отвечающих за учетные записи, права доступа и т.д.) будет интересовать совсем другая функциональность, нежели обычных пользователей.
Уважайте пользователей системы, не пишите инструкции в пренебрежительном стиле.
4. Особенности изложения
Помните, что стиль изложения в устной речи или в деловом письме отличается от оного в технической документации, и в частности, в руководстве пользователя.
Стиль руководства должен быть нейтрально-формальным – использование стилистически окрашенных слов отвлекает пользователя от сути.
Для составления хорошего документа пригодятся знания грамматики и немного психологии.
4.1 Пишите кратко и логично. Не давайте лишних деталей, не дублируйте информацию. Последовательность упоминания информации в руководстве пользователя должна совпадать с последовательностью действий пользователя:
Хорошо: In File menu, select Save item.
Хуже: Select Save item from File menu.4.2 Используйте повелительное наклонение, не употребляйте вежливые обороты (please, could и т.д.) — излишняя вежливость именно здесь будет помехой.
Хорошо: Click Logout to log out current user account from the system.
Хуже: It is needed to click Logout to log out current user account from the system.
Хуже: If user wants to log out current user account from the system (s)he needs to click Logout.
4.3 Структурируйте информацию. Часто можно встретить совет, что надо стараться избегать списков, однако, структурированная по шагам информация всегда лучше воспринимается.
Хорошо:
To create project:- Click the Create button on toolbar.
- On the CreateProject overlay fill in all mandatory fields.
- Click the Savebutton to save the project.
Хуже: To create project click the Create button on toolbar, on the Create Project overlay fill in all mandatory fields, click the Save button to save the project.
4.4 Не используйте будущее или прошлое время. Например, часто встречаются руководства, в которых реакция системы на действие пользователя передается фразами, сформулированными в будущем времени. У ПО нет прошлого или будущего: всё случается в настоящем как прямой результат конкретного действия пользователя. Как только событие случается, ПО реагирует.
Хорошо: When user clicks the Start button, the program starts the process.
Хуже: When user clicks the Start button, the program will start the process.
4.5 Проверяйте значение слов. Если необходимо писать документ на иностранном языке, надо стараться максимально избегать ошибок, связанных с недостаточным знанием языка.
Разумеется, орфографические ошибки недопустимы.
4.6 Не используйте синонимы для одного и того же термина. В IT литературе на английском (или любом другом) языке есть стандартный набор глаголов, обозначающих действия (click, double-click, select, type, press и т.д.) и такой же стандартный набор названий элементов управления. Определитесь с терминологией и придерживайтесь ее в рамках всего документа.
Например, не допускайте, чтобы в одной части документа выпадающий список назывался dropdown, а в другой точно такой же элемент – combobox или dropdown list. Это путает пользователя.
4.7 Разумно используйте сокращения и исключите жаргон.
Считается, что сокращения использовать не стоит, но если длинный термин употребляется несколько раз, то при первом упоминании в тексте надо писать полное название и рядом — аббревиатуру в скобках, а далее по тексту можно использовать только аббревиатуру. Если в документе есть глоссарий или раздел с сокращениями, они должны быть там расшифрованы.
Не используйте жаргонные слова, метафоры и термины, заимствованные из языка отличного от языка руководства.
5. Внешний вид
5.1 Продумайте стиль документа. Это может быть корпоративный шаблон или цветовая схема ПО или специально сделанный для документа дизайн.
При написании не стесняйтесь выделять важные вещи стилями или цветами (например, названия кнопок выделять жирным шрифтом). Но важно понимать, что неправильно подобранные шрифты и цвета могут затруднить восприятие содержимого документа.
5.2 Не экономьте место – разбивайте текст на короткие абзацы, используйте сравнительно крупные заголовки, начинайте новый раздел с новой страницы. Это облегчит восприятие прочитанной пользователем информации.
5.3 Используйте пиктограммы и иллюстрации. Существует мнение, что не стоит увлекаться иллюстрациями, а также включать в текст пиктограммы (icons) в руководстве пользователя. Однако графическая информация всегда лучше воспринимается и запоминается, поэтому снимки экрана и нужные пиктограммы должны присутствовать в хорошем руководстве в достаточном, но разумном количестве.
6. Поддержка
Не упускайте из виду тот факт, что ПО со временем меняется, а значит, ваш документ тоже должен меняться, чтобы оставаться актуальным.
Заключение
Примите к сведению, что раздражение от некачественного документа может быть спроецировано пользователем на ПО и, тем самым, повлиять на решение использовать продукт.
Помните главное: документ должен помогать пользователям.
Статью подготовила
![]()
Тарасюк Надежда, участник сообщества analyst.by,
Руководство программиста. Структура программы контроллера
АННОТАЦИЯ
Функционирование системы обеспечивается прикладным программным обеспечением (ППО).
ППО включает прикладное программное обеспечение промышленного компьютера (ППО ПК) и прикладное программное обеспечение программируемого контроллера (ППО ПЛК).1.2. Условия применения ППО ПЛК
Общая архитектура системы приведена на рисунке 1.![Структурная схема ПО]()
Рисунок 1. Общая архитектура ППО
Комплекс ПТС включает следующие аппаратные и покупные программные компоненты:
1) Два программируемых логических контроллера (ПЛК) QUANTUM на базе процессора P266 CPU, работающих в режиме горячего резерва. Исполнительная среда Unity Pro 4.1 XL.
2) Промышленный компьютер, состоящий из:
– персональная ЭВМ (встраиваемый промышленный компьютер);
– операционная система Windows XP Pro SP3;
– пакет визуализации СITECT 7
ПЛК осуществляют взаимодействие с внешними подсистемами по сети Ethernet (со стороны ПЛК) и по каналам ввода-вывода.
Взаимодействие ПЛК и промышленного компьютера осуществляется по сети Ethernet.
ПТС включает прикладные программные компоненты, разрабатываемые в соответствии с настоящим проектом:
Приложение Unity Pro, установленное на ПЛК.
Приложение Citect, установленное на ПК.2. ХАРАКТЕРИСТИКА ПРОГРАММЫ
2.1. Структура ППО ПЛК
Прикладное программное обеспечение ПЛК реализуется в виде приложения (см Рисунок 1), написанного в среде Unity v.4.1. Название приложения – upg.stu.
Приложение upg.stu обеспечивает реализацию функциональности системы, реализуемой на ПЛК для всех режимов работы.
Приложение содержит:
• конфигурацию аппаратных и программных средств;
• набор функциональных модулей, каждый из которых реализуется секциями, написанными на языке LD (лестничных диаграмм);
• набор функциональных блоков, разработанных в рамках проекта;
• базу данных;
• анимационные таблицы.
В состав приложения входят следующие функциональные модули, каждый из которых содержит один или несколько программных модулей, отраженных в таблице 1.
Таблица 1
Наименование секции Функциональность
Init Секция выполняется при первом цикле после запуска и обеспечивает присвоение начальных значений всем параметрам.
AI_to_AM Секция обработки входных аналоговых сигналов. Осуществляется вызов блока соответствующего сигнала для присвоения значения внутренней переменной и проверки достоверности канала.
DI_to_DM Секция обработки входных дискретных переменных. Производится вызов функционального блока соответствующего сигнала для присвоения значения внутренней переменной и проверки достоверности канала.
Comparing Секция сравнения получаемых значений с трех различных корзин распределённого ввода-вывода. Сигналы сравниваются по логике 2 из 3-х. Если два сигнала идентичны, а третий различен, то последний признается недействительным.
Наименование секции Функциональность
Alarms Секция обработки дискретных и аналоговых сигналов для определения достижений предельных значений. Выработка сигнализаций и команд на исполнение блокировок и защит.
INTERLOCK Секция формирования алгоритма блокировок и защит. В данной секции происходит запись в переменные, связанные с исполнительными механизмами.
SIM Секция управления режимами имитации и опробования контроллера.
DIAGNOSTIC Секция формирования диагностической информации контроллера.Промышленный компьютер позволяет производить управляющие воздействия только на деблокировочные ключи, посредством изменения состояния битов через управляющее слово. ПЛК информирует о своем состоянии через слово состояния. Описание отдельных полей (разрядов) слов данных приведено в Руководстве программиста.
Переменные в ПЛК кодируются следующим образом:
AI – аналоговый вход в ПЛК;
AIM – внутренний аналоговый вход ПЛК /ПК;
DI – дискретный вход в ПЛК;
DM – внутренний дискретный вход ПЛК /ПК;
Читайте также:
- Назначение и условия применения программ
