Edit me
Краткое справочное руководство выполняет иную функцию, нежели руководства по началу работы. Хотя руководство по началу работы помогает новичкам ориентироваться, предоставляя сквозную инструкцию для выполнения простого запроса API, краткое справочное руководство помогает пользователям получить представление о системе в целом, часто путем предоставления списка конечных точек API.
Необходимость в кратких справочных руководства
Будь то документация для конечного пользователя или документация для разработчика, в кратком справочном руководстве содержится 1-2-страничное руководство, где кратко описаны основные задачи и функции системы.
Краткое справочное руководство должно предоставить пользователю достаточно информации, чтобы понять суть системы, включая ключевые конечные точки и задачи. Часто конечные точки API имеют связь друг с другом, которые можно изобразить визуально. Вот пример диаграммы API, которую автор курса создал для одной из компаний:
Текст в диаграмме приведен на латинице по соображениям конфиденциальности, поэтому логика может быть не совсем очевидной. Но в этом API конечные точки организованы в разные группы. Некоторые из групп имели несколько уровней в конечной точке, и несколько опций включения для каждой конечной точки. Диаграмма была создана в Adobe Illustrator и опубликована в формате PDF. Разработчики сочли такой формат полезным, потому что был охвачен API в целом, показав, как все конечные точки соединены друг с другом в логической гармонии. Для документации API обычное дело, что в кратком справочном руководстве перечислены сокращенные описания конечных точек. По этой причине вывод Swagger UI часто может служить кратким справочным руководством.
Вне документации API краткие справочные руководства, как правило, больше ориентированы на задачи. Для сервиса установки или настройки, может имеет смысл делать руководство более описательным, меньше используя визуальный формат. Вот пример макета для такого руководства:
В случае документации API, как правило, краткое справочное руководство фокусируется на визуальной группировке или отображении конечных точек, поскольку именно это составляет основную функциональность API.
Преимущества чистой информации для изучения
Поскольку краткий справочник по сути представляет собой краткую сводку или описание всей системы, то информация собирается не только из одного источника. В результате, часто кажется, что у еще одного готового к работе технического писателя нет времени писать. Но для лучшего взаимодействия с пользователем не следует пропускать краткое справочное руководство, поскольку оно предоставляет неисчислимую ценность пользователям.
При создании краткого справочного руководства нужно стараться сжимать наиболее важную информацию в одну или две страницы, которые пользователи могут распечатать и закрепить на своей стене. Под “сжимать” не подразумевается сокращение шрифта до 6 пунктов, уменьшение начального значения и устранение всех пробелов. С помощью краткого справочного руководства нужно брать что-то надежное и сложное и минимизировать его до сути, но так, чтобы оно оставалось ясным для пользователей.
Благодаря такой “чистке” быстрые справочные руководства предоставляют пользователям уникальное преимущество в понимании материала. Предоставление общего обзора системы помогает пользователям получить представление целого, до углубления в детали.
Распределение больших объемов информации в кратко сформулированные заголовки, резюме, заголовки, мини-оглавления и тематические предложения может облегчить потребление и понимание информации. Краткие справочные руководства поднимают принцип очищения на другой уровень, сжимая всю систему в минимальный объем информации.
Краткие справочные руководства похожи на поэзию технического письма. Цель не просто быть кратким или консистентным. С поэзией поэт пытается вызвать настроение или нарисовать момент, и в этот короткий момент захватить сущность целого. Написание краткого справочного руководства требует практически таких же усилий. Дело не в простом сокращении слов, чтобы сделать документацию короче, или ограничении вывода несколькими темами, а в попытках сжать документацию в целом и выразить ее минималистский эквивалент.
Задача, вероятно, невозможна для технического материала. Тем не менее, попытка того стоит, и философия остается прежней. Краткие справочные руководства научат нас пользоваться системой за 5 минут, а не за 5 часов. Это философия упрощения и языковой эффективности.
Не стоит обманываться краткостью и масштабом краткого справочного руководства. При разработке такого руководства можно потратить несколько дней на написание только одной страницы. Но когда финал может быть отлит золотом!
Примеры краткого руководства
Ниже приведены примеры кратких справочных руководств на различных сайтах документации по API.
Eventful
Eventful предоставляет быстрый список всех конечных точек в API на одной странице, упорядоченный по группам ресурсов. Каждая конечная точка описана примерно в половину строки, поэтому можно быстро понять их все. Например, описание для /events/get в их кратком справочнике: «Получить запись о событии». Но если щелкнуть для получения более подробной информации, более подробное определение будет «При наличии идентификатора события возвращает данные о событии, связанные с этим событием». , См. http://eventful.com/events/E0-001-000278174-6 для примера интерфейса».
С первого взгляда на конечные точки можно получить определенное понимание. Взглянув с высоты на лес, можно увидеть форму леса в целом. Можно не знать, какие деревья содержит лес, но можно понять другие детали, которые не видны, когда видишь одно дерево.
Parse
Краткий справочник Parse похож на Eventful в том, что это длинный список конечных точек, на этот раз сгруппированный в таблицы. Эта справочная страница является просто разделом в одной длинной single page странице документации. При их подходе вся документация находится на одной странице, но при прокрутке вниз выделяются разные записи на боковой панели.
Иногда разработчикам нравится одностраничный подход, потому что он уменьшает фрагментацию информации и позволяет им использовать Ctrl + F, чтобы найти все экземпляры ключевого слова. Исследования компромиссов такого одностраничного подхода описаны в Single-page docs versus “Click Insanity”.
При использовании справочной документации OpenAPI на GitHub, заметно, что документация также содержится на одной странице. Разработчики могут использовать Ctrl + F, для быстрого поиска. Тем не менее такая документация обеспечивает много визуальной сложности для понимания пользователям.
Shopify
Краткое руководство Shopify не про API, но оно показывает фильтры, переменные и другие функции, доступные в Liquid, который является языком сценариев для разработчиков. Здесь Shopify использует функциональность свертывания и расширения для сжатия информации.
Такое краткое справочное руководство удобно тем, что позволяет одновременно просматривать все доступные функции в Liquid, чтобы знать, что нужно для получения дополнительной информации. Это как карта местности Liquid. Карта позволяет узнать все существующие функции.
👨💻 Практическое занятие: краткое справочное руководство
В своем найденном опен-сорс проекте найдем краткое справочное руководство. Ответим на следующие вопросы:
- Существует ли краткое справочное руководство по API? Возможно, список конечных точек API?
- Есть ли вывод Swagger UI, который служит кратким справочником по API?
- Если нет краткого справочного руководства, выиграет ли API от этого? Почему да или почему нет?
- Помимо списка сокращенных описаний конечных точек, что еще можно добавить в краткое справочное руководство API? Общие задачи?
- Есть ли несколько важных задач, которые пользователи должны выполнять с помощью API? Обсуждаются ли эти основные задачи в руководстве по началу работы?
🔙
Go next ➡
- Manuals
- Brands
- Olivetti Manuals
- Desktop
- Programma 101
- Reference manual
-
Contents
-
Table of Contents
-
Bookmarks
Quick Links
Related Manuals for Olivetti Programma 101
Summary of Contents for Olivetti Programma 101
-
Page 1
GENERAL REFERENCE MANUAL… -
Page 4
This manual discusses the operation and capabilities of Programma 101 in all of its modes. It is divided into a description of the computer, an explanation of its program language, and a brief presentation of the procedures and techniques for its programming and use. -
Page 5: Table Of Contents
Contents Page Computer Components … Memory ….Keyboard ….11 Decimal Wheel .
-
Page 6: Computer Components
Computer Components Programma 101 is composed of the following elements: Memory: To store numeric data and program instructions. Electric Keyboard: For numeric entry. manual operation, and compiling program instructions. Printing Unit: Serial printing. from right to left. at 30 characters per second; this unit prints all keyboard entries.
-
Page 7: Memory
Memory The memory is composed of ten registers. Eight are storage registers and two are used exclusively for instructions. The two instruction registers can store a total of 48 instructions. The eight storage registers, M, A, R, B, C, D, E and F, have a capacity of 22 digits, plus decimal point and sign.
-
Page 8
The following formats show the separation and capacities of the ten registers. Format 1 — This represents the storage registers used as complete registers: M, A, R: always complete; B, C, D, E, F: complete in this case. Format 2 — This represents the storage registers when split: b, B; c, C; d, D; e, E; and f, F. -
Page 9
— 9 –… -
Page 10
-10-… -
Page 11: Keyboard
Keyboard 1 The ON-OFF KEY is a dual purpose switch for both the ON and OFF positions. (Note: the OFF position automatically clears all stored data and instructions.) 2 The ERROR (reel) LIGHT lights when the computer is turned on, and whenever the computer detects an operational error;…
-
Page 12
— 12 -… -
Page 13
14 The ROUTINE SELECTION KEYS V, W, Y and Z direct computer proper program subroutine. 15 The NUMERIC KEYBOARD uses the ten-key entry system with provision for entry of a decimal point and a negative sign. Keyboard entries are automatically stored in the M register. -
Page 14
20 The PRINT KEY prints the contents of an addressed register. 21 The CLEAR KEY clears the contents of an addressed register. When the computer is operated manually, a depression of this key will print the number in that register and clear it. 22 The TRANSFER KEYS perform transfer operations between the storage registers and the operating registers. -
Page 15: Decimal Wheel
Decimal Wheel As it affects COMPUTATION: The Decimal Wheel determines the number of decimal places to which the result of a calculation in the A register will be carried out. The Decimal Wheel has the following effect on these operations. ADDITION, SUBTRACTION, After the computation, the result in the A MULTIPLICATION:…
-
Page 16: Split Register
Split Register As was pointed out in the preceding pages, each of the B, C, 0, E and F registers can be split into two parts, each with a capacity of 11 digits plus decimal point and sign. The left part of the register is identified with the lower case letter corresponding to its companion’s designation.
-
Page 17: General Operations
General Operations Start-S The instruction «S» (used in creating a program) directs the computer to stop and release the keyboard for the entry of figures or the selection of a subroutine. After figure entry, the program is restarted by touching the Start key (5). The program can also be restarted by touching a Routine Selection key.
-
Page 18: Data Transfer Operations
Data Transfer Operations To A An instruction containing the operation “ » directs the computer to transfer the contents of the addressed register to A while retaining them in the original register. The contents of M and R are not affected. The previous contents of A are destroyed. The setting of the Decimal Wheel has no effect on this operation.
-
Page 19: From M
From M An Insrruction containing the operation » “ directs the computer to transfer the contents of M to the addressed register while retaining them in M. The contents of registers A and R are unaffected by this instruction. The original contents of the addressed register are destroyed. The setting of the Decimal Wheel has no effect on this operation.
-
Page 20: Exchange
Exchange An instruction containing the operation » » directs the computer to exchange the contents of the A register with the contents of the addressed register. The contents of M are not affected except by the exchange between A and M. The contents of the R register are not affected. The setting of the Decimal Wheel has no effect on this operation.
-
Page 21: D-R Exchange
D-R Exchange The instruction «RS» directs the computer to exchange the contents of D (both D and d registers) with the contents of the R register. The setting of the Decimal Wheel has no effect on this operation. This instruction has a special use in the following cases exclusively: •…
-
Page 22: Decimal Part To M
Decimal Part To M The instruction «/ » directs the computer to transfer the decimal portion of the contents of A to the M register while retaining the entire contents in A. The original contents of the M register are destroyed. The R register is not affected by this instruction. The setting of the Decimal Wheel has no effect on this operation.
-
Page 23: Arithmetic Operations
2. The operation Is carried out in the M, A and R registers Programma 101 can perform these arithmetic operations: +, -, X, +, V. and absolute value. Figures are accepted and computed algebraically. A negative value is entered by depressing the negative key at any time during the entry of a figure.
-
Page 24: Addition
Addition An instruction containing the operation » » directs the computer to add the contents of the selected register (addend) to the contents of the Aregister (augend) and is executed in two phases: 1ST PHASE Transfer the contents of the selected register (addend) to M, while retaining them in the original register.
-
Page 25: Subtraction
Subtraction An instruction containing the operation » » directs the computer to subtract the contents of the selected register (subtrahend) from the contents of the A register (minuend) and is executed in two phaaes: 1ST PHASE Transfer the contents of the selected register (subtrahend) to II, while ratalnlng them In the original register.
-
Page 26: Multiplication
Multiplication An instruction containing the operation » » directs the computer to multiply the contents of the selected register (multiplicand) by the contents of the A register (multiplier) and is executed in two phases: 1ST PHASE Transfer the contents of the addressed register to M, while retaining them in the original register.
-
Page 27: Division
÷ ÷ ÷ ÷ Division ÷ ÷ ÷ ÷ An instruction containing the operation » » directs the computer to divide the contents of A register (dividend) by the contents of the selected register (divisor) and is executed in two phases: 1ST PHASE Transfer the contents of the addressed register to M, while retaining them…
-
Page 28: Square Root
√ √ √ √ Square Root √ √ √ √ An instruction containing the operation» «directs the computer to: 1ST PHASE Transfer the contents of the selected register to M, while retaining them in the original register. 2ND PHASE Extract the square root of the contents of M, as an absolute value, obtaining in A the result truncated according to the setting of the Decimal Wheel.
-
Page 29: Absolute Value
Absolute Value The absolute value instruction «A » changes the contents of the A register, if negative, to positive. EXAMPLE: Decimal Wheel set at 2. ______________________________________ BEFORE AFTER — 29 -…
-
Page 30: Jump Operations
Jump Operations The Jump operation directs the computer to depart from the normal sequence of step-by-step instructions and jump to a pre-selected point in the program. These instructions provide both internal and external (manual) decision capability and are useful to: •…
-
Page 31: Unconditional Jumps
Unconditional Jumps ∆ ∆ ∆ ∆ A∆ ∆ ∆ ∆ these jumps are executed whenever the instruction is read C∆ ∆ ∆ ∆ B∆ ∆ ∆ ∆ List of Unconditional Jump Instructions: ____________________________________________________ ______POINT OF ORIGIN REFERENCE POINT_______ D∆ ∆ ∆ ∆ E∆…
-
Page 32: Conditional Jumps
Conditional Jumps / ∆ / ∆ / ∆ / ∆ a∆ ∆ ∆ ∆ these jumps choose one of two alternatives by testing the contents of the A register for the fol/owing condition: c∆ ∆ ∆ ∆ b∆ ∆ ∆ ∆ If the contents of the A register are: GREATER THAN 0 — the program jumps to the corresponding Reference Point.
-
Page 33
The Conditional Jump can not directly differentiate between a negative value and zero. If the A register has a negative value, the distinction may be made by a two-test procedure: 1. The value of A is tested. If the jump occurs, this value is positive; if the jump does not occur, the A (absolute value) instruction is executed. -
Page 34: Constants
Constants Constants in Registers Programma 101 can store numeric values (e.g. constants) to be used within the program on the magnetic card. Numeric values entered into the registers 0, E and F, or their splits, can be directly stored together with the program on the magnetic card when the RECORD PROGRAM switch is ON (in).
-
Page 35: Constants As Instructions
Constants as Instructions It is sometimes necessary to conserve registers for several accumulations and, therefore, advisable to avoid storing constants in these registers. There is a method for generating values within a program by converting the required number into computer instructions, one for each digit.
-
Page 36: Computer Utilization
Computer Utilization To Record a Program Once the sequence of steps to solve a problem has been developed on coding sheets, the operator enters the program into the computer by depressing the keys corresponding to the instruction sequence. 1. Turn computer ON 2.
-
Page 37: Read/Record D And E
Read/Record D and E Constants and instructions: 1) can be entered from the keyboard directly into registers E and D; 2) can be recorded from only registers E and D onto a card; or; 3) read from a card only into registers E and D, without affecting the contents of other program registers.
-
Page 38: To Use A Program
Automatic Internal Checks Programma 101 provides a system of automatic internal checks to assure the operator that all components are functioning properly. The red ERROR light is the visual indication that a mis- operation has been detected.
-
Page 39: Manual Mode
Manual Mode Programma 101 can be operated manually as an electronic calculator. The rules given in the preceding pages for computer instructions apply also to manual operations with the following exceptions: 1. The results of multiplication, division and square root will be printed automatically.
-
Page 40: Computer Exercise
Computer Exercise The following exercise shows you Assuume a = 9 and b = 3; how to: The following operatIonl solve the problem manually: • use the Programma manually • write a program Turn the computer ON. Programma prints Depress the GENERAL RESET key. The problem used is: Turn the RECORD PROGRAM switch OFF (out).
-
Page 41
The following instructions solve the same problem in program mode: Starting Point of Program. Clear register for accumulation of answers. Stop program for entry of factor a. Transfer factor a to B /. Stop program for entry of factor b. Transfer factorb to B. -
Page 42: Changing The Ribbon
Changing The Ribbon 1. Remove print unit cover and pull paper tape holder forward. 2. Move the ribbon reverse levers away from the spools (see diaagram) 3. Remove spools and ribbon and discard. 4. Replace the spools and thread the ribbon as indicated in the diagram.
-
Page 43: Insertion Of Paper Roll
Insertion of Paper Roll 1. Remove the paper roll bar (a) and discard the old spool. 2. Place the new roll between the two holders, so the tape feeds from underneath, and insert paper roll bar. 3. Turn Programma on. 4.
-
Page 44: Programming Techiques
Programming Techniques Following are some frequently encountered mathematical statements and suggested Programma solutions, assuming the value a is in the A register: ÷ ÷ ÷ ÷ (a + 1) Divide a by itself creating 1 in the A register. Add a to 1 giving ( a + 1) ÷…
-
Page 45: Rounding Techniques
Rounding Techniques Following are routines for rounding to the setting of the Decimal Wheel in addition, subtraction and multiplication. Assume one value is stored in the B register and the second value in the e register: ___________________________________________________________________________ ADDITION SUBTRACTION MULTIPLICATION ___________________________ Transfer first value to A register.
-
Page 46
METHOD 2: Assume the divisor is in register B and the dividend is in register A. Double dividend. ÷ Divide doubled dividend by the divisor. Special series to generate 2 in the M register. ÷ Divide doubled quotient by 2. Round off. -
Page 47: Instruction-Data Storage
Instruction — Data Storage Storage of data and instructions in the same half of a register. A technique has been developed which allows the storage of both a number and program instructions in the same half of a register (F, f, E, e, D, d). This technique permits the programmer to address a register having both a number and instructions in it, and perform any transfer, arithmetic, print or clear operation with the number — without disturbing the instructions in that register and without getting an error light.
-
Page 48
3. The instruction immediately following the space allotted for the number must be either a stop (an S) (see Fig. 3) or an A reference point (AV, AW, AY, AZ, aV, aW, aY, or aZ) (see Fig. 4. Unless it is a ‘signal stop,’ there is no restriction on the instruction immediately preceding the space allotted for the number. -
Page 49
Generation of Constants Following is a routine to generate a constant to the setting of the Decimal Wheel, e.g., with the Decimal Wheel at 4 generate constant 0.0003: Following is a routine to generate a constant to one position more than the setting of the Decimal Wheel, e.g., with the Decimal Wheel at 4 generate constant 0.00005: — 49 -… -
Page 50: Counters
Counters When programming a loop that is to be cycled a specified number of times, the most direct way of accomplishing this is to use one register as a counter, which initially has an index stored in it. This index is reduced by 1 each time the loop is cycled. When the count reaches 0 we may exit the loop.
-
Page 51: Packing A Register
Packing a Register This routine illustrates the concept of «packing» a register. Frequently, it becomes necessary to store a group of constants in just one register. The following routine exemplifies how each of the constants might be stored in one register and isolated for manipulation. Let us assume that we wish to store the constants .453, .281, .397, and .024 all in one register.
-
Page 52: The Domino Technique
The Domino Technique This program illustrates a procedure referred to as «the domino technique.» This technique is particularly useful in applications such as a moving average in which the entry of each subsequent value displaces the contents of every register in the sequence like a row of dominoes.
-
Page 53: Chaining
D and d prior to any arithmetic operation or ……. reference to the R register. On the following pages is a typical program from the Olivetti Underwood program library which illustrates many of the techniques described previously. — 53 -…
-
Page 54: Sample Program
This program will perform an unweighted least square’s fit to a parabolic function: y = ax given as input a set of X pairs. The program consists of three sides of a card and will yield the fol lowing information: — SIDE A — INPUT: OUTPUT:…
-
Page 55
— SIDE C — (INTERCEPTS FOR PLOTTING THE FUNCTION ON LOG — LOG PAPER) INPUT: OUTPUT: Log a (from any curve desired) (Intercept with X = 1) -1/b (Intercept with Y = 1) if k = 10 then (E) = Log 10 = 2.3025 850930 k = e then (E) = 1 Unless altered, the program computes all logarithms to the base 10. -
Page 56
PROGRAM INSTUCTIONS SIDE NO. A REG. 1 REG. 2 REG. F REG. E REG. D CONTENTS OF REGISTERS Operand D / + Operand A √ A √ Operand A √ A √ C / + A √ A √ A √ A / V A √… -
Page 57
PROGRAM INSTUCTIONS SIDE NO. B REG. 1 REG. 2 REG. F REG. E REG. D CONTENTS OF REGISTERS D /x E /x A √ E/ — B/ + ÷ B/ x ÷ D/ x ÷ A √ C / + REG. -
Page 58
PROGRAM INSTUCTIONS SIDE NO. C REG. 1 REG. 2 REG. F REG. E REG. D CONTENTS OF REGISTERS B / * ÷ A / Y A / V ÷ REG. 1 REG. 2 REG. f REG. e REG. d Lower case letters are entered with the corresponding upper case letters and /; e.g., b = B/. CONSTANTS ON CARD KEYS TO CONSTANTS ON CARD… -
Page 59
OPERATING PROCEDURE OPERATIONS DIGIT CAPACITY DECIMAL WHEEL SETTING 7 — 10 WHOLE NOS DECIMALS Depress General Reset Key Turn Record Program OFF Turn Print Program OFF Insert Side A of Program Card Depress V Enter Xi and Depress Start Enter Yi and Depress Start Return to Step 6 unti data is exhausted. -
Page 60
OPERATING PROCEDURE OPERATIONS DIGIT CAPACITY DECIMAL WHEEL SETTING 7 — 10 WHOLE NOS DECIMALS Depress RS Computer prints: Log a Return to Step 1 for a new set of points. If it is desired to plot the fitted curve on Log-Log paper go to Step 16 Depress General Reset Key Insert Side C of Program Card… -
Page 61
11, 38 wheel, 11, 15 Packing a Register, 51 testing for, 33 Decimal Part to M, 22, 47, 51 Paper Roll, 43 Division, 27 Print Key, 14, 17 olivetti canada Limited 447-3351 1390 Don Mills Road, Don Mills, Ontario… -
Page 62
Title No. of No. of Date Code cards instructions REG. 1 REG. 2 REG. F REG. E REG. D CONTENTS OF REGISTERS REG. 1 REG. 2 REG. f REG. e REG. d Lower case letters are entered with the corresponding upper case letters and /; e.g., b = B/. CONSTANTS ON CARD KEYS TO CONSTANTS ON CARD…
Существует множество видов предоставления справочной информации пользователю – это и FAQ (frequently asked questions, часто задаваемые вопросы) и онлайн справка и руководство пользователя (user guide) и популярные сегодня подсказки (coachmarks, см. пример ниже), обучающие видео и другие.
Существуют разные причины, по которым требуется написать руководство пользователя системы. Начиная с просьб заказчика (в моей практике был случай, когда заказчику надо было поставлять руководство пользователя после каждой итерации, чтобы с его помощью он смог бы провести приемочное тестирование функциональности итерации) и заканчивая условиями контракта, касающимися поставки готового ПО, если говорить о разработке ПО на заказ. В случае разработки собственного продукта написание руководства пользователя тоже часто имеет место.
К созданию руководства часто привлекают аналитика, если нет возможности поручить техническому писателю. В подавляющем большинстве случаев самыми полными знаниями о системе обладает именно аналитик, он же обладает умением ясно излагать свои мысли в письменной форме в силу специфики профессии. Поэтому, мне не однократно приходилось сталкиваться с созданием руководств пользователя.
Ниже я приведу несколько практик для составления хорошего руководства пользователя. Часть из них, возможно, кому-то будут полезны и при написании спецификаций требований.
1. Стандарты
Часто бывает нужно написать документ, который бы удовлетворял требованиям действующих стандартов. Это могут быть:
- IEEE Std 1063-2001, «IEEE Standard for Software User Documentation»;
- ГОСТ 19:
- ГОСТ 19.402-78 ЕСПД. Описание программы;
- ГОСТ 19.502-78 ЕСПД. Общее описание. Требования к содержанию и оформлению;
- ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению;
- ГОСТ 19.504-79 ЕСПД. Руководство программиста. Требования к содержанию и оформлению;
- ГОСТ 19.505-79 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.
Если потребности проекта позволяют вам не следовать жестким стандартам, в любом случае изучение этих документов может послужить стартовой точкой для написания качественного документа.
Также может оказаться полезной книга Юрия Кагарлицкого 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 Create Project overlay fill in all mandatory fields.
- Click the Save button 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 Проверяйте значение слов. Если необходимо писать документ на иностранном языке, надо стараться максимально избегать ошибок, связанных с недостаточным знанием языка.
Например, глагол «press» означает нажатие клавиши на клавиатуре, а «click» – нажатие кнопки или значка в окне программы при помощи мыши, а «hit» вообще является жаргонным словом.
Разумеется, орфографические ошибки недопустимы.
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,
аналитик с 6-летним опытом в сфере.
Предложите, как улучшить StudyLib
(Для жалоб на нарушения авторских прав, используйте
другую форму
)
Ваш е-мэйл
Заполните, если хотите получить ответ
Оцените наш проект
1
2
3
4
5
С т а с к е в и ч Н. Л. Справочное руководство по газоснабжению. Л., 1960. 875 с. [c.354]
Стандартизировать обработку грузовых единиц на предприятии позволяет применение внутрифирменного справочного руководства по таре и упаковке, в разработке которого должны принимать участие все заинтересованные службы. Основу руководства может составлять следующая информация [c.404]
Более подробно порядок выполнения операции деления описан в специальных справочных руководствах. [c.9]
При заполнении накладной экспедитору надлежит пользоваться Алфавитным списком железнодорожных станций (книга 2) Тарифного руководства №4, Единой тарифно-статистической номенклатурой грузов в разделе Б части 1 Тарифного руководства №1 и частью 2 этого Руководства Прейскуранта №10-01 для расчета провозной платы, а также знать статистические коды обслуживаемых грузоотправителей и грузополучателей, иметь под рукой справочные руководства грузоподъемности подвижного состава, степеней негабаритное , принятых сокращений по видам упаковки и др. [c.165]
Финансово-кредитный словарь в двух томах представляет собой справочное руководство по всем отраслям финансовой науки и практики. Он предназначается для широкого круга работников финансовой системы и кредитных учреждений, для финансистов, экономистов-плановиков и бухгалтеров предприятий, совнархозов, министерств, ведомств и других советских и хозяйственных организаций, для преподавателей и студентов высших и средних экономических, финансовых и кредитных учебных заведений. [c.3]
Данная глава является кратким обзором терминов, которые вы, возможно, слышали в применении к техническому анализу. Необходимо ли вам их знать Не сейчас. Считайте это лишь кратким справочным руководством. [c.244]
Приемы и методы финансового анализа постоянно меняются и совершенствуются, для того чтобы соответствовать требованиям динамичной инвестиционной среды. Учебный курс и программы экзаменов также все время обновляются для отражения последних достижений аналитической теории. После утверждения кандидатуры соискателя звания FA ему отправляют Учебное руководство, содержащее детальный список литературы для изучения. Вся программа основана на домашнем изучении, и Институт формально не проводит никаких учебных занятий. Однако он совместно с координаторами учебных программ FA региональных обществ аналитиков или с колледжами и университетами организует учебные группы. Для того чтобы помочь кандидатам в обучении, Институт периодически публикует справочные руководства, учебники и списки рекомендуемой литературы. [c.938]
Книга Ф. Никсона представляет собой справочное руководство практически по всем аспектам обеспечения качества и надежности. [c.13]
Справочное руководство. В справочном руководстве подробно описаны все внешние характеристики программного изделия. Оно обеспечивает пользователя подробной информацией о назначении программного изделия о необходимом оборудовании и его конфигурации о языке программирования, включая форматы команд и сообщений, структуры входных и выходных данных о взаимосвязях с другими программными изделиями. При этом предполагается, что читатель справочного руководства имеет опыт работы с техническими и программными средствами ЭВМ. [c.139]
Справочное руководство составляется на основе внешней спецификации. Дополнительные исходные материалы представляет группа разработки. Это руководство предназначено для программистов или системных аналитиков, которые являются непосредственными пользователями программного изделия. Предполагается, что они имеют опыт работы на ЭВМ по-крайней мере в течение одного года. [c.139]
Справочный буклет. Справочный буклет имеет карманный формат и содержит краткие сведения из справочного руководства. Он позволяет быстро ознакомиться с форматами операторов, мнемоникой операций, таблицами преобразования кодов, синтаксисом языка. В наиболее сжатой форме этот документ называется также справочным формуляром. [c.140]
Группа выпуска документации начинает участвовать в работе над программным изделием в рамках фазового обзора I, выполняя предварительную оценку стоимости издания документации. Для этого приходится принимать некоторые предположения относительно вида документации, времени издания и расценок. Чем определеннее составлены стандарты оформления документации, тем точнее окажутся оценки, полученные в этой фазе. Если, например, для транслятора с РПГ решено выпустить справочное руководство, руководство оператора и указатель сообщений, то этого уже достаточно, чтобы более менее точно рассчитать затраты на выпуск документации. [c.141]
Независимо от того, насколько хорошо все сотрудники понимают методы работы, принятые в их организации, среди сотрудников во взглядах на производственные задачи не будет до конца того единодушия, которое требуется для выполнения каждого конкретного задания. Создание универсального программного обеспечения, предназначенного для неизвестных режимов работы, является слишком сложным делом, чтобы множество людей имело одинаково полное представление об изделии. Им необходимы справочные руководства. [c.328]
Даже если какой-то сотрудник правильно представляет организацию собственной работы, ему довольно трудно будет ясно изложить свои замыслы коллегам, если не упорядочить эти замыслы тем или иным способом. Для этого также необходимы справочные руководства. [c.328]
Техническое описание системы Справочное руководство Справочный буклет Руководство оператора Указатель системных сообщений [c.346]
Ковелю Дж. А. Бизнес-планы. Полное справочное руководство. — М. Бином, 1999. [c.228]
В последнее десятилетие необходимым условием успеха любых организаций, от коммерческих до некоммерческих (благотворительных обществ, больниц и университетов) было признано повышение эффективности маркетинга. Но, несмотря на это, до сих пор отсутствует четкое понимание его сущности, методов и границ. В самом деле, многие предполагаемые последователи этой науки ошибочно отождествляют две далеко не главные функции маркетинга — рекламу и продвижение товара — с концепцией, связанной с созданием взаимовыгодных отношений обмена. И любое авторитетное и всеобъемлющее справочное руководство, подобное этому, должно служить разрушению заблуждений, так же как и давать столь необходимое руководство в области понимания сущности, методов и границ маркетинга. [c.12]
Эта книга не только представляет и описывает все внутренние особенности японских свечей, но в дальнейшем может служить и справочным руководством. Каждая модель свечей будет определена и описана в стандартной форме, так что вы сможете быстро получить необходимую вам справку. Я представлю новый метод анализа, называемый фильтрацией свечей , который, по моим наблюдениям, чрезвычайно полезен для лучшего распознавания моделей. Вы увидите, что популярность его растет, поскольку он являет собой надежное основание для последующего анализа и исследований. [c.14]
Франсуа А. Справочное руководство по вопросам организации Пер. с франц. В 2 т. — Париж, 1985. — Т. 2. [c.130]
Франсуа А. Р. Справочное руководство по вопросам организации В 2 т. Пер. с франц. — Париж, 1985. [c.229]
Книга, таким образом, является и предметом системного изложения важной области знаний и методов, и справочным руководством для специалистов, и учебным пособием для желающих продвинуться в этой области деятельности, [c.12]
Иначе, однако, обстоял вопрос в отношении цен. Согласно объявленному ОПЕК намерению установить твердый уровень справочных цен примерно на 40% выше рыночных, чтобы восстановить, как заявляла ОПЕК, старое соотношение 1 к 1,4 между рыночными и справочными ценами, цену на 1974 г. надо было установить на уровне примерно 25 долл. за баррель, тогда как всего лишь три года назад она составляла 1,6 долл. О такой цене явно не могло быть и речи, но в декабре 1973 г., когда члены ОПЕК собрались для обсуждения создавшегося положения, у них не было единой позиции. Некоторые из них, например Саудовская Аравия, считали, что производители не должны извлекать слишком большие коммерческие выгоды из искусственно созданной нехватки, вызванной в основном политическими соображениями. Другие же, Иран, Ирак и Алжир, которые сильнее нуждались в доходах, считали драматическое повышение цен в порядке вещей. Наконец, опять-таки под руководством шаха, было принято окончательное решение снова повысить цены вдвое на основе простого принципа обеспечения отчислений в пользу стран-производителей, эквивалентных стоимости добычи нефти из сланцев. Таким образом, страны-потребители, и без того уже глубоко встревоженные политическими последствиями ограничений на поставки нефти, внезапно столкнулись с таким повышением цен на нефть, которое превзошло их худшие опасения, —повышением, [c.280]
ТЕХНИЧЕСКОЕ нормирование работ по испытанию скважин. Справочное руководство. 16 л., 1 р. Авт. Сомова М. С., Шкляр М. Г., Горячев Б. И., Акопян А. С. [c.232]
Ковелло Дж. А, Хейзелгрен Б. Дж. Бизнес-планы. Полное справочное руководство. Перевод с англ. — М. Лаборатория базовых знаний, 1999. [c.860]
В справочных руководствах, в принципе, имеются указания и методики гидравлического расчета входных участков косогорных труб. Как правило, в них отмечается, что конструкции с криволинейными боковыми стенками, вызывающие слабые деформации свободной поверхности, имеют чрезмерно большую протяженность. Поэтому рекомендуются и входные участки с плоским дном и ломаными боковыми стенками. В их пределах образуются косые волны, которые взаимопересекаясь и отражаясь от стенок, проникают в водопропускную трубу и распространяются в, ней на значительном протяжении. При значительных углах сужения бурного потока в плане наблюдается либо образование прямых прыжков, либо продольных гребней, глубина виды в которых в 6 много раз[превышает с глубину потока в конце быстротока. Иногда она может превышать1 высоту тр убы, что угрожает разрушением насыпи. [c.180]
Скоростная обработка металлов резанием, Справочное руководство, ВПТИ, 1954. [c.273]
Годфруа Ж. Что такое психология в 2-х т. Т. 2. — М. Мир, 1992. С. 58. О надежности и валидности тестов см., например Клайн Пол. Справочное руководство по конструированию тестов. — Киев, ПАН Лтд, 1994. Иванцевич Дж., Лобанов А. А. Человеческие ресурсы управления. — М. Дело, 1993. С. 224-225. [c.180]
В первом томе восьмитомного учебно-справочного руководства Общие сведения о нефти и нефтепродуктах [c.7]
В. Г. Афонин, Л. М. Гейман, В. М. Комир. Справочное руководство по взрывным работам в строительстве (Киев Буд1вельник , 1974 г.) и др. [c.283]
Примечание. Непараметрические ранговые методы за последнюю четверть века зарекомендовали себя как бурно развивающаяся область математической статистики. Эти методы в силу своих преимуществ над традиционными применяются не только в экономико-статистических расчетах, но и при обработке данных в естественно-научных, инженерных, медицинских, космических и многих других исследованиях. На русском языке основы теории ранговых методов представлены книгой Я. Гаека и 3. Шида-ка, справочным руководством М. Холлендера и Д. Вульфа, моно- [c.114]
Справочное руководство в каждом случае представляет собой процедуры выполнения работы, зафиксированные на бумаге. В последние годы напечатано много книг и статей, посвященных как опробованным на практике, так и новым системам и процедурам, вопросам их внедрения и использования. Специалистам по программному обеспечению хорошо известна книга Брэндона, описывающая стандарты управления в обработке данных [65], Брэндон отделяет методические стандарты (общепринятую практику и способы выполнения работы) от рабочих стандартов. В данной книге рассмотрены только методические стандарты, которые в свою очередь подразделяются на методы управления и методы программирования. Кроме того, что методы программирования (стандартные соглашения по кодированию программ, полезные практические приемы и примеры плохо написанных программ, которым не следует подражать, форматы входных и выходных данных, протоколы сообщений и системы стандартных характеристик) очень нужны, в данной книге о них ничего не говорится. Эта книга в основном посвящена методам управления и организации работы как должны быть оформлены документы и что они должны содержать, как обеспечить обратную связь, как осуществлять конфигурационное управление изделием Путь внедрения методов управления — написание процедур, регламентирующих методику работы. [c.329]
Справочное руководство и справочный буклет должны быть готовы в окончательном виде в большом количестве (можно ксерокопии) на этапе Д21 (разд. 7). Это требуется фирме AB Servi es для проведения обучения. [c.373]
ОБУЧАЮ1ЩЯ ПРОГРАММА. В течение этой, таксказать, официальной части обучения новички получают (или обновляют) основные знания и вырабатывают навыки, необходимые в их работе. Например, продавцы изучают политику компании, правила работы на кассовом терминале и простейшие правила продажи товаров те, кто будет работать на складе, учатся правильно принимать и оформлять товар. Программа обучения может включать лекции, аудио- и видеокурсы. Новые работники получают справочные руководства и изучают правила веде- [c.306]