LLC "Техническа документация. Накратко и по същество: как правилно да съставите инструкции за потребителите
В раздела Източници, използвани в разработката, посочете списък с научни и технически публикации, нормативни и технически документи и други научни и технически материали, които са посочени в изходния текст.
Обяснителната бележка е съставена от специалисти по разработка софтуери за специалисти със същото ниво на квалификация. Затова е уместно да се използва специална терминология, да се позовава на специална литература и т.н.
11.3. Упътване за употреба
Както бе споменато по-горе, в момента често се използва друг оперативен документ, който отчасти включва ръководство системен програмист, програмист и оператор. Този документ се нарича Ръководство на потребителя. Появата на такъв документ е следствие от широкото разпространение персонални компютри, работейки върху които потребителите комбинират посочените трима специалисти.
Изготвянето на документация за потребители има свои собствени характеристики поради факта, че потребителят по правило не е професионалист в областта на разработката на софтуер. Книгата на S. J. Grimm дава препоръки за писане на такива програмна документация:
вземете предвид интересите на потребителите - ръководството трябва да съдържа всички инструкции, необходими на потребителя;
бъдете ясни и използвайте кратки изречения;
избягвайте технически жаргон и тясно специализирана терминология, ако все пак е необходимо да използвате някои термини, те трябва да бъдат обяснени;
бъдете точни и рационални - дългите и объркващи ръководства обикновено не се четат от никого, например по-добре е да предоставите чертеж на формуляр, отколкото да го описвате надълго и нашироко.
Ръководството за потребителя обикновено съдържа следните раздели:
обща информация за софтуерния продукт;
описание на монтажа;
описание на старта;
инструкции за работа (или описание на потребителския интерфейс);
съобщения до потребителя.
Глава Главна информацияОтносно програматаобикновено съдържа името на софтуерния продукт, Кратко описаниенеговите функции, прилаганите методи и възможните области на приложение.
Разделът за инсталиране обикновено съдържа Подробно описаниедействия за инсталиране на софтуерния продукт и съобщения, които могат да бъдат получени.
Разделът Стартиране по правило описва стъпките за стартиране на софтуерния продукт и съобщенията, които могат да бъдат получени.
Глава Инструкции за работаобикновено съдържа описание на режимите на работа, входно/изходните формати и възможните настройки.
Глава Съобщения към потребителятрябва да съдържа списък възможни съобщения, описание на тяхното съдържание и действията, които трябва да бъдат предприети в отговор на тези съобщения.
11.4. Ръководство на системния програмист
Съгласно GOST 19.503-79 ръководството на системния програмист трябва да съдържа цялата информация, необходима за инсталиране на софтуера, конфигуриране и тестване на неговата функционалност. В допълнение, както бе споменато по-горе, той често включва описание на необходимата поддръжка, която преди това е била предоставена в ръководството за оператора (GOST 19.505-79) и/или ръководството поддръжка(ГОСТ 19.508-79). Понастоящем тази диаграмаизползвани за съставяне на ръководство на системния администратор.
Ръководството на системния програмист трябва да съдържа следните раздели:
Обща информация за софтуерния продукт,
структура,
настройка,
Преглед,
допълнителни функции,
съобщения до системния програмист.
Разделът Обща информация за програмата трябва да включва описание на предназначението и функциите на програмата, както и информация за техническите и софтуеркоито осигуряват изпълнението на тази програма (например силата на звука оперативна памет, изисквания за състав и параметри външни устройства, софтуерни изисквания и др.).
В глава Структура на програмататрябва да се предостави информация за структурата на програмата,
нея компоненти, връзки между компонентии за връзките с други програми.
Разделът Настройка на програмата трябва да съдържа описание на стъпките за настройка на програмата за условията на практическа употреба.
Разделът Тестване на програмата трябва да съдържа описание на начините за проверка на функционалността на програмата, например тестови примери.
В глава Допълнителни функциитрябва да се предостави описание допълнителни функциипрограми и начини за достъп до тях.
В глава Съобщения до системния програмистТрябва да бъдат посочени текстовете на съобщенията, издадени по време на конфигуриране и тестване на програмата, както и по време на нейното изпълнение, описание на тяхното съдържание и действията, които трябва да бъдат предприети в отговор на тези съобщения.
11.5. Основни правила за изготвяне на софтуерна документация
При подготовката на текстови и графични материали, включени в документацията на програмата, трябва да се придържате към действащите стандарти. Някои разпоредби на тези стандарти са дадени по-долу.
Дизайн на текст и графичен материал. Текстовите документи се изготвят на листове с размер А4, докато графичните клетва могат да бъдат представени на листове с размер А3. Полетата на листа се определят в съответствие с общите изисквания: ляво - най-малко 30, дясно - най-малко 10, горно - най-малко 15 и долно - най-малко 20 mm. В текстовите редактори за проектиране на бележка параметрите на страницата се подреждат в зависимост от печатащото устройство. При ръчно попълване на документи параметрите на страницата се избират за удобство.
Всички страници са номерирани непрекъснато. Номерът е отбелязан горе вдясно с арабска цифра. Страниците включват както листове с текстове и снимки, така и листове с приложения. Първата страница се счита за заглавна. Номерът на страницата не е посочен на заглавната страница.
Изписани са имената на секциите с главни буквив средата на линията. Разстоянието между заглавията и текста, както и между заглавията на раздели и подраздели, трябва да бъде равно на:
при машинописно изпълнение на документ - два интервала;
ръкописно - 10 mm;
използвайки текстови редактори- определя се от възможностите на редактора. Имената на подразделите и параграфите трябва да бъдат с отстъп и отпечатани
извън реда с главна буква, без подчертаване и без точка накрая. Разстояние между последен редтекстът на предишния раздел и последващото заглавие, когато са разположени на една страница, трябва да бъде равен на:
при изпълнение на документ чрез машинопис - три интервала;
при ръкописно изпълнение - минимум 15 mm;
при използване на текстови редактори – определя се от възможностите на редактора.
Разделите и подразделите се номерират с арабски цифри с точка. Разделите трябва да имат поредни номера 1, 2 и т.н. Номерът на подраздела включва номера на раздела и сериен номерподраздел, включен в този раздел, разделени с точка. Например: 2.1, 3.5. Препратките към параграфи, раздели и подраздели показват, като се използва поредният номер на раздела или параграфа,
например „в разд. 4", "в клауза 3.3.4".
Текстът на разделите се отпечатва през 1,5-2 интервала. При използване на текстови редактори височината на буквите и цифрите трябва да бъде най-малко 1,8 мм (шрифтове № 11-12).
Офертите трябва да бъдат номерирани с арабски цифри със скоби, например: 2), 3) и т.н. - с абзацно отстъп. Разрешено е да се маркира изброяване чрез поставяне на тире пред текстов елемент или символ, който го замества в текстови редактори.
Проектиране на чертежи, алгоритъмни диаграми, таблици и формули. В съответствие с GOST 2.105-79 " Общи изискваниякъм текстови документи” илюстрации (графики, диаграми, диаграми) могат да бъдат дадени както в основния текст, така и в приложението. Всички илюстрации се наричат рисунки. Всички фигури, таблици и формули са номерирани последователно с арабски цифри ( непрекъсната номерация) или в рамките на раздел (относително номериране). В приложението - в рамките на приложението.
Всяка рисунка трябва да има надпис - заглавие, поставено под рисунката, например:
Фиг. 12. Форма на прозореца на главното меню
Всички фигури, таблици и формули в бележката трябва да имат връзки във формата: „(фиг. 12)“ или „формата на прозореца на главното меню е показана на фиг. 12".
Ако пространството позволява, фигурите и таблиците трябва да бъдат поставени непосредствено след параграфа, в който са споменати за първи път, или възможно най-близо до този параграф на следващите страници.
Ако чертежът заема повече от една страница, всички страници с изключение на първата се отбелязват с номера на чертежа и думата „Продължение“. Например:
Ориз. 12. Продължение
Фигурите трябва да бъдат поставени така, че да могат да се разглеждат, без да се обръща страницата. Ако такова поставяне не е възможно, снимките трябва да бъдат позиционирани така, че за преглед страницата трябва да се завърти по посока на часовниковата стрелка. В този случай горният ръб е левият ръб на страницата. Местоположението и размерите на полетата са запазени.
Алгоритъмните диаграми трябва да бъдат направени в съответствие със стандарта ESPD. Дебелината на плътната линия при изчертаване на алгоритъмни диаграми трябва да бъде от 0,6... 1,5 mm. Надписите върху диаграмите трябва да бъдат направени с чертожен шрифт, височината на буквите и цифрите трябва да бъде най-малко 3,5 mm.
Номерът на масата е поставен вдясно горен ъгълили преди заглавката на таблицата, ако има такава. Заглавието, с изключение на първата буква, се изписва с малки букви.
Резултатите от теста са показани в табл. 4.
Номерът на формулата се поставя с правилната странастраници в скоби на ниво формула. Например:
z: =sin (x)+In (y); |
Дизайн на приложения.Всяко приложение трябва да започне с нова страницаобозначаващи в десния ъгъл думите „КАНДИДАТСТВО” с главни букви и имат тематично заглавие. Ако има повече от едно заявление, всички те се номерират с арабски цифри: ПРИЛОЖЕНИЕ 1, ПРИЛОЖЕНИЕ 2 и т.н. Например:
ПРИЛОЖЕНИЕ 2
Заглавна страница на споразумението и обяснителна записка
Фигурите и таблиците, поставени в приложението, са номерирани с арабски цифри във всяко приложение с добавяне на буквата „P“. Например:
Ориз. Позиция 12 - 12-ти чертеж на приложението; Ориз. Ш.2 - 2-ра снимка на 1-во приложение.
Ако приложението съдържа текста на програмата, тогава всеки файл е проектиран като чертеж с името на файла и неговата цел, например:
Ориз. P2.4. Файл menuran.pasпрограма за движение на курсора на главното меню.
Изготвяне на списък с литература.Библиографията трябва да включва всички използвани източници. Информацията за книги (монографии, учебници, ръководства, справочници и др.) трябва да съдържа: фамилия и инициали на автора, заглавие на книгата, място на издаване, издателство, година на издаване. При трима или повече автори се допуска посочване на фамилията и инициалите само на първия от тях с думите „и т.н.“. Издателството трябва да се цитира изцяло в именителен падеж: допуска се съкращение на името само на два града: Москва (М.) и Санкт Петербург
Информацията за статия от периодично издание трябва да включва: фамилията и инициалите на автора, името на статията, публикация (списание), поредица (ако има), година на издаване, том (ако има), номер на публикацията ( списание) и номерата на страниците, на които е поставена статията.
11.6. Правила за изготвяне на изчислителни и обяснителни бележки за курсов дизайн
Когато изготвяте обяснителни бележки, трябва да се придържате към GOST 7.32-91 (ISO 596682) „Доклад за изследователска работа. Правила за структура и дизайн." Според този стандарт Текстов документтози тип трябва да включва:
заглавна страница,
абстрактно,
съдържание,
Въведение,
основната част,
заключение,
списък на използваните източници, включително литература,
приложения.
Заглавната страница е съставена в съответствие с GOST 19.104-78 " една системасофтуерна документация. Основни надписи“ (фиг. 11.1).
Втората страница е резюме или анотация за разработката софтуер. Резюмето в съкратен вид трябва да съдържа информация за обема на документа, броя на илюстрациите, таблиците с приложения и др., както и списък ключови думии основните положения на документа. Например, за доклад за изследователска работа: описание на обекта на изследване, цели на работата, методи и оборудване за изследване, получени резултати, препоръки за изпълнение и др. Анотацията също описва накратко целта и характеристиките на разработката, но тя обикновено не включва информация за обем и т.н.
Трета страница - съдържание, включително: въведение, имена на всички раздели, подраздели, параграфи, заключение, списъци с литература и приложения указващи номера на страници.Нито анотацията или резюмето, нито самото съдържание са споменати в съдържанието.
След това следват разделите на документа в реда, определен от логиката на представяне на материала. Това може да бъде последвано от приложения, съдържащи материал, който не е включен в документа поради ограничения му обем, но е интересен за по-задълбочено разбиране на представения материал.
Като пример, разгледайте съдържанието на обяснителната бележка към проекта за курса „Технология на програмирането“.
Въведение................................................. ......................................................... ............. ..................................... .......... | |
1. Избор на технология, език и среда за програмиране ............................................ ............ ............................ | |
2.Анализ и изясняване на изискванията към програмния продукт.................................................. ........... ............. | |
2.1.Анализ на процеса на обработка на информацията и избор на структури | |
данни за неговото съхранение ................................................. ......................................................... ............. .............. | |
2.2. Избор на методи и разработване на основни алгоритми за решаване на проблема.................................................. | |
3.Развитие блокова схемасофтуерен продукт................................................ ......... ............. | |
4. Дизайн на потребителския интерфейс ............................................. ......................................................... | |
4.1.Изграждане на диалогова графа..................................... ......... ................................................ ............... ..... | |
4.2. Разработване на информационни входно-изходни форми.................................................. ........... ........................ | |
5. Проектиране на класове на домейни ................................. ............... ................................. ..... | |
5.1. Конструиране на класова диаграма..................................... ......................................................... ......... | |
5.2 Изясняване на структурата на домейн класовете | |
и разработване на алгоритми на метода..................................... ................. ................................. ........... | |
6. Избор на стратегия за тестване и разработване на тестове..................................... ......... ........................ | |
Заключение..................................................... ................................................. ...... ............................................ | |
Библиография.................................................. ................................................. ..... ............................ | |
Приложение 1. Технически спецификации............................................. ......................................................... ............. .. | |
Приложение 2. Ръководство на потребителя..................................... ......................................................... |
Контролни въпроси
1.Назовете основните видове софтуерна документация. Опишете всеки от тях. В какви случаи се използват?
2. Какво трябва да бъде описано в обяснителната бележка? За кого е предназначено? Защо една обяснителна бележка обикновено описва не само взети решения, но и отхвърлени варианти?
3. За кого е предназначено ръководството за потребителя? Какво трябва да съдържа? В какви ситуации четете ръководството за употреба? Помислете за ръководствата за потребителя, които сте чели. Какво не ви хареса в тях?
ПРИЛОЖЕНИЕ
Система символиУнифициран език за моделиране (UML)
Unified Modeling Language UML – всъщност стандартно средство за защитаописания на проекти, създадени с помощта на обектно-ориентиран подход. Моделът на софтуерния проект, както е предвидено от авторите на езика, може да включва голям бройдиаграми различни видове, използвайки унифицирана нотационна система. Сред диаграмите най-често използваните са:
диаграми на случаи на използванеили прецеденти (използва диаграми на случаи) - показва основните функции на системата за всеки тип потребител;
класови диаграми(диаграми на класове): контекстуални, описания на интерфейси и имплементации - демонстрират връзките на класовете един с друг;
диаграми на активността(диаграми на дейност) - представляват диаграма на потоците на управление за решаване на определена задача с помощта на отделни действия, позволяват наличието на паралелни и/или алтернативни действия;
диаграми на взаимодействие(диаграми на взаимодействие) от два алтернативни типа:
а) диаграми на последователности (диаграми на последователност) - показват подреденото във времето взаимодействие на обекти по време на изпълнението на случай на употреба,
б) диаграми на сътрудничество(диаграми на сътрудничество) - предоставят същата информация като диаграмите на последователностите, но във форма, която ви позволява да представите по-добре отговорностите на класовете като цяло;
диаграми на състоянието на обекта(statechart diagrams) - показват състоянията на даден обект и условията за преминаване от едно състояние в друго;
пакетни диаграми(диаграми на пакети) - демонстрират връзките между набори от класове, комбинирани в пакети;
компонентни диаграми(схеми на компоненти) - покажете кои софтуерни компонентиот какво се състои софтуерът и как тези компоненти са свързани помежду си;
диаграми за поставяне(диаграми за разполагане) - ви позволяват да свържете софтуерни и хардуерни компоненти на системата.
Допълненията към диаграмите са формализирани и неофициални текстови описания, коментари и речници.
При конструирането на тези и други диаграми се използва унифицирана система за обозначения. Обозначенията на прецедентните диаграми са дадени в табл. Позиция 1, класови и пакетни диаграми - в табл. Позиция 2, диаграми на взаимодействие - в табл. П3, диаграми на дейности и състояния на обекта - в табл. Позиция 4, схеми на компоненти и разположение - в табл. P.5. Ако е необходимо, е позволено да се използват обозначенията на някои диаграми върху други.
Ръководство за потребителя като софтуерна (оперативна) потребителска документация
Документът "Ръководство на потребителя" се отнася за пакета оперативна документация. Основната цел на ръководството за потребителя е да предостави на потребителя необходимата информация за самостоятелна работа с програма или автоматизирана система.
По този начин документът Ръководство на потребителя трябва да отговори на следните въпроси: какъв вид програма е, какво може да прави, какво е необходимо, за да се гарантира правилното й функциониране и какво да се направи в случай на повреда на системата.
Документация: софтуерна/оперативна/потребителска документация
Вещ: програма, софтуерен компонент на комплекс или система
Публика: потребители на програмата, т.е. лица, които я използват за решаване на собствени приложни проблеми
Задачи: дават възможност на потребителите напълно самостоятелно да усвояват и прилагат програмата
Ръководните стандарти за създаване на документ за ръководство за потребителя може да включват: RD 50-34.698-90 в стр. 3.4. "Упътване за употреба", така ГОСТ 19.505-79 „Ръководство за оператора. Изисквания за съдържание и дизайн".
Могат да се разграничат следните основни раздели на ръководството за потребителя:
Предназначение на системата;
Условия за използване на системата;
Подготовка на системата за работа;
Описание на операциите;
Извънредни ситуации.
Предназначение на системата
Този раздел от документа Ръководство на потребителя трябва да съдържа информация за предназначението на системата, нейните цели и цели.
Пример:
„Корпоративният интранет портал е предназначен да подобри корпоративната култура и да организира ефективно взаимодействие между служителите.
Основната цел на Port е да създаде единно информационно пространство за предприятието и да оптимизира работата на служителите чрез улесняване на комуникациите между тях и оптимизиране на редица бизнес процеси.“
Условия за използване на системата
Този раздел от документа Ръководство на потребителя трябва да включва всички онези фактори, които са необходими за правилната работа на системата. Тук има няколко подраздела:
Изисквания към хардуер– тук можете да включите изисквания за конфигурацията на компютъра на потребителя, софтуера, необходим за работата на Системата, както и наличието на допълнително оборудване (принтер, скенер и др.), ако е необходимо;
Квалификации на потребителя - този подраздел трябва да съдържа изисквания за уменията и знанията на потребителя ( пример: „Потребителите трябва да имат способността да работят с операционна система Windows");
Подготовка на системата за работа
Този раздел от документа Ръководство на потребителя трябва да съдържа инструкции стъпка по стъпка за стартиране на приложението. Етапът на подготовка на системата за работа включва инсталиране на допълнителни приложения (ако е необходимо), идентификация, удостоверяване и др.
Описание на операциите
Това е основният раздел на документа Ръководство за потребителя, който съдържа инструкции стъпка по стъпка за потребителя да извърши определено действие.
Ако работата на автоматизирана система засяга цял бизнес процес, тогава в ръководството за потребителя, преди да се опишат операциите, е препоръчително да се предостави информация за този процеснеговата цел и участници. Подобно решение позволява на човек ясно да си представи ролята си в този процес и функциите, които се изпълняват за него в системата.
По-нататък в Ръководството на потребителя трябва да се предостави описание на функциите, разбити на отделни операции. Необходимо е да се подчертаят подраздели, които описват функциите на този процес и действията, които трябва да бъдат предприети, за да бъдат изпълнени.
Пример:
„4.1 Одобрение на проекта
Този процес има за цел да организира работата на служителите, участващи в разработването и одобрението на проекта.
Авторът на проекта създава запис в Системата и прикачва пакет от необходимата документация, след което проектът се предава за одобрение от ръководството. След преглед на проекта, мениджърите могат да го потвърдят или да го изпратят на Автора за преработка.
4.1.1 Създаване на проект
За да създадете проект, трябва да кликнете върху бутона “…” на панела “…” и да попълните следните полета във формуляра, който се появява:
Име на проекта;
Описание на проекта;
Следните полета се попълват автоматично:
Дата на създаване на проекта – текуща дата;
Колкото по-подробно са описани действията със системата, толкова по-малко въпроси ще има потребителят. За по-лесно разбиране на всички принципи на работа с програмата, стандартите в документа Ръководство за потребителя могат да включват диаграми, таблици и илюстрации, изобразяващи екранни форми.
За големи автоматизирани системи се препоръчва да се създаде отделно ръководство за всяка потребителска категория (потребител, модератор и т.н.). Ако при работа със системата са разпределени допълнителни потребителски роли, тогава е препоръчително да поставите таблица с разпределение на функциите между ролите в документа Ръководство за потребителя.
Извънредни ситуации
Този раздел от документа Ръководство на потребителя трябва да съдържа инструкции стъпка по стъпка за действията на потребителя в случай на повреда на системата. Ако потребителят не е подложен на специални изисквания за администриране на операционната система и т.н., тогава можете да се ограничите до фразата „Ако системата се повреди или работи неизправно, трябва да се свържете със системния администратор“.
Методология и стил на представяне на ръководството за потребителя
Ръководството за потребителя може да бъде или бърз справочник за основната функционалност на програмата, или пълен урок. Методика за представяне на материала в в такъв случайще зависи от обхвата на самата програма и изискванията на клиента.
В зависимост от характеристиките на програмата и целева аудиторияРъководството за потребителя по отношение на начина на представяне на материала може да се доближи до учебник или, обратно, до справочник. Определя се редът на представяне на материала в ръководството за потребителя гледна точка на потребителяпрограми.
Ако програмата е инструмент, който ви позволява да решавате практически задачи от определен краен набор, ръководството предоставя стандартни процедури за решаване на всяка от тях. Например потребител пощенски клиенттрябва да знаете как да напишете и изпратите съобщение, как да изтеглите нови съобщения от сървъра, как да отговорите на съобщение и т.н. Всяко от тези действия може да бъде разделено на последователни елементарни стъпки, поне за типични ситуации. IN основна програмаподобен потребителски задачиможе да има много, но не безкрайно много. Ръководството за потребителя, изградено на принципа на потребителските задачи, прилича на учебник, въпреки че по правило липсва методическият апарат, присъщ на учебниците: тестови задачи, въпроси, упражнения.
Ако програмата представлява среда, в която потребителят може самостоятелно да решава възложени от него проблеми, ръководството за потребителя трябва да е по-близко до справочник. Той трябва последователно и систематично да описва всички функции на програмата и реда на тяхното използване. Какво да прави с тях, къде да ги насочи, потребителят ще мисли сам (или ще се запише за курсове за обучение). И така, в ръководството за потребителя за графичен редакторще намерим описание на всички графични примитиви, инструменти, филтри, но няма да се каже директно как да се изобрази сграда, кола или, да речем, куче. Потребителят или знае как да рисува, или не.
Възможни са и други потребителски гледни точки. Има програми, чрез които потребителят контролира състоянието на конкретен обект, например промишлена инсталация. Тогава ръководството за потребителя се изгражда на принципа на таблица: съобщението на програмата - реакцията или възможните реакции на потребителя.
Ако потребителят използва програмата за решаване на проблеми в нетривиални предметни области, силно се препоръчва да се включи концептуален раздел в ръководството за потребителя. Той трябва да описва начина, по който програмата прилага представяне на обекти от реалния свят, така че потребителят да има добра представа с кои от тях и на какво ниво на абстракция може да работи.
@ Журавлев Денис
Много ИТ компании, които разработват и поддържат софтуер и автоматизирани системи, са изправени пред задачата да създадат потребителска документация за своите продукти в съответствие с изискванията на GOST.
По правило необходимостта от документация в съответствие с GOST възниква в сътрудничество с държавни организации, големи индустрии и компании, при разработването на софтуер по поръчка за търгове и държавни поръчки или ако е необходимо да се добави софтуерен продукт към " Единен регистърРуски програми за електроника компютрии бази данни (регистър на местен софтуер)“.
Има две серии (набори) стандарти, които регулират набора създадени документии правила за тяхното проектиране при разработване на автоматизирани системи, комплекси и софтуер:
- ГОСТ 34 - Автоматизирани системи
- GOST 19 - Единна система за програмна документация (USPD)
От една страна, предполагам, че тези два стандарта се конкурират помежду си различни опциипълнота на проектната документация. От друга страна, те се фокусират върху различни аспекти и следователно се допълват добре.
GOST 34 основно определя пълнотата, видовете, структурата и съдържанието на създадените документи.
GOST 19 до голяма степен определя правилата за изготвяне на документи.
Следователно на практика и двата GOST често се използват наведнъж.
Ако говорим конкретно за документация за краен потребителсистема, тогава от списъка с документи, описани в GOST 34, се интересуваме от „Ръководството на потребителя“. В GOST 19 документ с подобно значение се нарича „Ръководство на оператора“, но за софтуера това е първата опция, която се използва най-често.
Ръководство за потребителя идва с всеки продукт, програма или система. Той трябва да предоставя на потребителя информация за свойствата на продукта, неговата функционалност, как да го използва и как да работи с него.
За начинаещ технически писател или обикновен специалист, който неочаквано е натоварен да подготви ръководство за потребителя на GOST, тази задача е сериозен проблем.
Не само трябва да се изучава голямо числорегулаторни документи, пълни с кръстосани препратки и написани на сложен, прекалено чиновнически, почти юридически език, също е необходимо да се изберат от там изискванията, които се отнасят конкретно до типът, който се създавадокумент. След това, по време на цялата работа, трябва постоянно да наблюдавате спазването на тези изисквания в работния документ, като постоянно проверявате стандартите.
Обикновено проблемът се задълбочава от липсата на време от писането потребителска документация, за съжаление, често се приема в самия край на проекта, точно преди крайния срок - датата на доставка или стартиране на системата.
За опитен технически писател документирането според GOST може да не причини сериозни затруднения. Но дори и за него изготвянето на шаблони за нови документи, привеждането на съществуващата документация към изискванията на стандартите или проверката на окончателния документ за съответствие с тези изисквания може да отнеме значително време.
Dr.Explain опростява създаването на ръководство за потребителя съгласно GOST
Започвайки от версия 5.5.1100, програмата за създаване на потребителска документация Dr.Explain предлага функцията за автоматизирана поддръжка на GOST в проекти. Тази функция е предназначена да улесни много живота на потребителите, които са изправени пред задачата да създадат ръководство за потребителя в съответствие с изискванията на държавните стандарти.
По-специално, програмата Dr.Explain контролира и автоматизира поддръжката на следните стандартни изисквания:
- Наличие на задължителни раздели на документа „Ръководство за потребителя“ [GOST 34 RD 50-34.698-90]. Всички раздели са снабдени с обяснения на тяхното съдържание.
- Дизайн на заглавни страници, анотации и съдържание [GOST 19.105-78, 19.104-78].
- Параметри на отпечатаните страници на документ и местоположението на основните елементи върху тях [GOST 19.106-78].
- Структура и дизайн на горните и долните колонтитули [GOST 19.106-78].
- Дизайн на текстовата част на документа: стилове на шрифта, абзацни отстъпи, разстояние между редовете[ГОСТ 19.106-78].
- Формиране и проектиране на заглавия, раздели, изброявания (списъци) [GOST 19.106-78].
Управлението на функцията за поддръжка на GOST за проект е достъпно в Настройки на проекта в раздела са често срещани.
Когато режимът на поддръжка на GOST е активиран за проекта, съответният потребителски настройкиза печатни формати RTF\DOC и PDF автоматично се застъпват от програмата, което гарантира пълно съответствие на параметрите на изходните документи с изискванията на стандартите.
За събота и неделя HTML форматии CHM, потребителските настройки ще се използват независимо дали режимът на поддръжка на GOST е активен. Това премахва ограничението за свободен стил на тези формати и позволява, например, да се проектира онлайн помощ изцяло в корпоративен или тематичен стил.
Важно:
Важно:Функцията за поддръжка на GOST е достъпна в Dr.Explain само в руската версия на интерфейса. Езикът на интерфейса на програмата се избира в менюто Настройки\Избор на програмен език (Опции\Език на приложението).
Създаване на ново ръководство за потребителя съгласно GOST
За да създадете ново ръководство за потребителя съгласно изискванията на GOST 34 в програмата Dr.Explain, можете да използвате команди от менюто Файл\Създаване на локален проект - Ръководство за потребителя съгласно GOST 34или Файл\Нов генерален проектна tiwri.com - Ръководство за потребителя съгласно GOST 34
или подобни бутони начален екранприложения.
Програмата ще създаде нов проект, който вече съдържа шаблона заглавна страница, резюме, съдържание и задължителни раздели, форматирани съгласно GOST.
Текстът на всеки раздел ще предостави кратка инструкция за това какво трябва да бъде включено в този раздел. Потребителят трябва само да попълни секциите с подходящо съдържание.
Настройките на дизайна за печатни формати RTF/DOC и PDF ще бъдат зададени в съответствие с изискванията на GOST 19.
Привеждане на съществуващата потребителска документация в съответствие с изискванията на GOST
Също така програмата Dr.Explain ви позволява да приведете съществуващата потребителска документация в съответствие с изискванията на GOST.
Важно:Преди да активирате режима на поддръжка на GOST за проекти, които вече съществуват във формат Dr.Explain, трябва да направите резервно копие gui файл на проекта.
Ако изходната документация все още не се поддържа в Dr.Explain, но се съхранява в други формати, първата стъпка е да импортирате съществуващи документи в програмата. Dr.Explain поддържа импортиране на документи от редица популярни формати. Командите за импортиране са налични както в началния прозорец на програмата, така и в менюто Файл.
След това трябва да активирате режима за поддръжка на GOST в свойствата на проекта по описания по-горе начин. Програмата ще провери структурата на документа за наличието на необходими раздели и ако липсват, ще ги създаде. Останалите съществуващи раздели, чието присъствие не се регулира от GOSTs, ще бъдат преместени в раздела „скрити от експорт“ Старо преградно дърво”.
Потребителят ще трябва да плъзне и пусне съдържанието на тези секции или цели секции в основното дърво на проекта и да ги редактира, ако е необходимо.
Както в първия случай, настройките на дизайна за печатни формати RTF/DOC и PDF ще бъдат зададени в съответствие с изискванията на GOST 19.
Ще имаш нужда
- - 100% познаване на устройството или софтуерния продукт, за който се пише ръководството;
- - познания в областта на лингвистиката;
- - писмени умения.
Инструкции
Управление потребителили, с други думи, ръководството с инструкции е документ, предназначен да предостави помощ при използването на някаква негова система потребителм. За съставяне на ръководството потребителтрябва да познавате описаната система на сто процента, но я погледнете през очите на някой, който не знае нищо. Да поемем лидерството потребителза определена софтуерна програма, която все още няма аналози. Представете си, че се сблъсквате с тази програма за първи път. Откъде трябва да започнете? Какво трябва да знаете първо? Организирайте тези знания в категории по важност.
Като разделите цялата информация, свързана с вашето творение, на групи, вие сте направили план за написване на ръководство потребител. Започнете да описвате работата във вашата програма от самото начало, оставяйки за накрая най-сложните подробности относно, да речем, възможностите за препрограмиране или работа с критични грешки. На този етап трябва да имате готово съдържанието на ръководството. потребител– една от задължителните части на този документ.
Ако ръководството, което създавате, е предназначено за използване в голяма компания, тогава трябва да обърнете внимание на приетите там корпоративни стандарти. Например в много руски компанииРъководствата за потребителя не се приемат без илюстративна подкрепа, с други думи, снимки, обясняващи написаното. В ръководството потребителВ допълнение към съдържанието трябва да има и други задължителни части: - Резюме, т.е. обяснение общи задачиръководство и описания продукт - въведение, което обяснява информацията, свързана с ръководството потребителдокументи и методи за използване на ръководството; - раздели, обясняващи използването на продукта на различни етапинеговото използване, например първи стъпки, ремонт или профилактика; - раздел с често задавани въпроси и отговори на тях; - речник или.
Обикновено чрез създаване на ръководство потребителтехническият писател е лице, което има всички необходими познания както за езика, така и за описания продукт. Когато се занимавате с дейностите на технически писател без подходящо обучение, трябва да запомните няколко правила. Първо, не трябва да се прекалява с използването на специални термини, които не са разбираеми за обикновения човек. потребител. Второ, всеки използван термин трябва да бъде описан и обяснен подробно. Трето, трябва да пишете възможно най-ясно и кратко. И накрая, един технически писател трябва да може да погледне на собственото си писане през очите на обикновен човек. потребителда видите недостатъците на собствения си текст.
Ех... това е "живот"!
С личен пример се убедих, че писането на ръководства за потребителя не е толкова голяма работа. проста задача... Особено ако не знаете софтуерния продукт, върху който трябва да го изградите!
И така, как се пише ръководство за потребителя?
Неотдавна си намерих работа нова работана фирма, която се занимава с разработка и внедряване на софтуерен продукт... всичко щеше да е наред.. но се спънах още при първата си задача..
Получих задачата да напиша ръководство за потребителя за програма, която дори не бях виждал преди (изглежда като нещо от счетоводство, в което не съм много добър). Няма стари версии на ръководства за потребителя, няма примери... само аз и програмата... В процеса на работа се натъкнах на някои клопки, които ще се опитам да опиша в тази статия.
Изглежда, че може да е трудно! Има програма... малко мозъчна атака- и всичко е готово!!! Разбира се, най-идеалният вариант е, ако ръководството за потребителя е написано от самия разработчик на „чудото на природата“ или поне от потребител, който работи в описаната система от дълго време.
Какво да направите, ако това не е така?! Първата стъпка е да изтичате до разработчика и наистина да „седнете на врата му“, така че той да „дъвче“ своето „детище“ от самото начало до най-екстремното ниво!!! В такива случаи е по-добре да си представите себе си като „Защо“ и да стигнете до дъното на най-малките подробности. За съжаление, нервите на програмиста няма да оценят такъв импулс! Но и тук изборът е прост добър водач, или разменете любезности и само...
Във всеки случай трябва да погледнете програмата „отвън“ през очите на пионер! След предварително идентифициране на функционалните модули и модула, който представлява най-голям интерес за крайния потребител (най-добре е да се опише подробно!), е необходимо да се определи нивото на детайлност на проектираното ръководство. Обикновено този въпрос се обсъжда с ръководството на организацията разработчик, но може да се направи по ваша преценка.
Според моя опит, когато пишете ръководство за потребителя, е по-добре да отделите малко време за дизайна обща структураобяснителна бележка, след което пишете за всеки функционален модулотделни ръководства. Факт е, че колкото по-стандартизирано (структурирано) е ръководството, толкова по-лесно е за потребителя да се ориентира и толкова по-лесно е да се опише! С добре обмислена структура на описание, вероятността да „забравите“ да покажете някои ключов моментзначително намалени!
Има и един такъв добра точка- това са GOSTs! За описание на ръководствата за потребителя има такъв прекрасен GOST като GOST 19.505-79 ( за описание вижте раздела на сайта).
Как се пише ръководство за потребителя:
Основната насока за писане на ръководството е следното описание:
- цел на програмата (защо изобщо е необходима, към кого е насочена и т.н.);
- съобщения до оператора (описание възможни грешки, потребителски съобщения и др.).
- условия за изпълнение на програмата (минимални и максимални хардуерни и софтуерни изисквания);
- изпълнение на програмата (описание на функционалността на програмата, последователност от действия на оператора и др.);
Като пример мога да предложа собствен метод за описание на изпълнението на програмата. Първо, трябва да анализирате целия описан софтуерен продукт и да определите разбивката на отделни модули (секции и т.н.).
В същото време трябва да дефинирате функции на менюто, повтарящи се имена на полета и други функционалности, които са стандартни в целия модул, раздел на софтуерния продукт и др.
1. Кратко описание
2.Модул А
- Подмодул A.1
- Подмодул A.2
3.Модул Б
- Подмодул B.1
- Подмодул B.2
Секцията „Кратко описание“ съдържа кратко описание на модули A и B, а също така описва тези повтарящи се елементи от менюто, имена на полета и т.н., характерни за двата модула. По-нататък в описанието на самия модул/подмодул е описано кратък алгоритъмработа с модул/подмодул (изтегляне, преглед, добавяне, редактиране, изтриване, генериране на отчети и т.н.), след което се предоставя по-подробно описание на всички функционалности и всички налични полета. С други думи всичко е в детайлите !
Описани са особеностите на полетата, какви операции се извършват при попълването им, какви стойности се присвояват автоматично, в какви случаи изобщо се показват полетата, видовете полета, всички бутони, квадратчета за отметка.. Като цяло, тук можете да описвате до безкрайност!!!
Ако модулът съдържа подмодули, тогава е по-добре всичко да се опише в строга последователност.. Т.е. в началото опишете самия модул (от началото до края), като същевременно направите линк към съответния подмодул, а по-долу - опишете подробно целия подмодул! Оказва се достатъчно Хубава снимка! Потребителят не трябва да прескача от една част на документа в друга и обратно.
И така е описан целият софтуерен продукт. В края можете да напишете списък със съкращенията, използвани при описание на ръководството за потребителя.
Няма съмнение, че тази техника е обобщена! Но от моя опит мога да кажа със сигурност, че е много удобно! Удобно за потребителя, удобно за разработчика на ръководството за потребителя! Всички са щастливи.. 😉
Но както се казва, приятел по вкуса няма! Можем само да ви пожелаем успешно развитие!
Вижте сродни статии