Writing Technical Instructions with Sample James (Graves) Barakaat
Contents
1. click OK Disk Administrator E3 The partition number of the partition which contains your Windows NT system files has changed The old partition number was 3 the new partition number is 4 Edit BOOT INI to reflect this change before shutting the system n Figure 9 Disk Administrator Message 2 Now the partition needs to be formatted Right click on the F to display popup menu Figure 10 f ass k Administrator m Fault Tolerance Tools View Options Help F FAT Unknown B Unknown isome owove sloom ME Assigt ie Bl Primary partition Logical drive _ Volume set Format AStart S ochNvwHERE wailing Disk Administrator E Document WordPad soPM Figure 10 Disk Administrator Display with Popup Menu 12 5 Select the Format menu option The Format dialog is displayed Figure 1 1 Format F L2 x Capacity Unknown capacity File System NTFS Allocation Unit Size Default allocation size Volume Label parl T Format Options Quick Format Enable Compression ee Figure 11 Format Dialog Display 6 Format the disk with the NTFS file system and enter DATA as the label name NOTE DO NOT Enable Compression 7 Click Start A WARNING message is displayed 8 Click OK After the format is complete a dialog is displayed stating the format operation is complete 9 Click Close in the Format2. operating systems multi 0 disk 0 rdisk 0 partition 4 WINNT Windows NT Server Version 4 00 multi 0 disk 0 rdisk 0 partition 4 WINNT Windows NT Server Version 4 00 VGA mode basevideo sos multi 0 disk 0 rdisk 0 partition 3 WINNT Disaster Recovery multi O disk O rdisk O partition 3 WINNT Disaster Recovery VGA mode basevideo sos C MS DOS 6 After reviewing the boot ini click Save to save the file even if changes have not been made A dialog is displayed stating that the file was successfully saved 7 Click OK to continue The server will reboot 8 When the server restarts select the Disaster Recovery option from the boot menu and Press Enter to continue 9 Login to Windows NT with an administrative equivalent ID Create Volume Set 1 From the Start Menu select Programs gt Administrative Tools Common gt Disk Administrator A graphical view of the logical and physical disks is displayed Figure 5 Disk Administrator OE x Partition Fault Tolerance Tools View Options Help e a Disk 0 C D EISA Utiilie FAT FAT Eie Snaus EAS SSG 8IBBMB 36MB 502MB 1502MB 2040MB 4108 MB CD ROM 0 E r Primary pation Logical drive n pp Figure 5 Logical and Physical Disk display 2 Press and hold down the Ctrl key while clicking on both of the sections labeled Free Space 10 Right click on th
3. step describe what the reader will see or what the result s will be 3 The next action step etc There are slight variations on this and you should use illustrations or screen shots if they are available The illustration is placed in the step where the action on it is stated Note Never use an acronym without first defining it unless it is widely known to your audience It is best to define the acronym in all cases especially in technical scientific and business writing Example Incorrect The TSC installation is performed after Log on Correct The Terminal Services Client TSC installation is performed after Log on Once you have defined the acronym it is okay to use it in the same message Test the instructions with a representative sample of the users Observe the problems that the user may encounter with the instructions and make revisions accordingly You may have to do this more than once You will be amazed at what you find that could make the instructions more usable This is a method of usability testing that should especially be done with instruction manuals It is important to make sure that the users of the representative sample understand that the manual is being tested and not them After the manual has made a final revision it is best to convert the manual to PDF before putting it on the web server The document that follows titled Operational Recovery can be used as an example for writing technical
4. Assumptions This topic assumes the catastrophic failure of a Windows NT 4 0 server at the home office Tasks Create Disaster Recovery Diskettes Insert installation CD ROM Insert the Cheyenne Disaster Recovery Disk Scan tape backup sessions Start Disaster Recovery Create Volume Set Format Volume Set Restore Data CONDOOaARWND Procedure for Locally Connected Tape Device Create Disaster Diskettes Create the Disaster Recovery DR diskettes There are four diskette images on WWCH1DOO2INSTALLNNTSRVA4OWBBOOTDISK cheydr01 dsk cheydr02 dsk cheydr03 dsk cheydr04 dsk To Create the diskettes run disaster bat 2 Assuming the restore is happening on the same physical hardware Recreate the system as a new hardware unit see Compaq Proliant xxxx Server Installation Procedures for your specific hardware platform 3 Boot the system with the Windows NT Server setup disk 1 cheydr01 dsk image diskette created above You are prompted to insert the Windows NT Server setup diskette 2 4 Insert the Windows NT Server setup disk 2 cheydr02 dsk image diskette created above You will be prompted to select the setup type Express or Custom 5 Press the C key to select a custom setup This allows us to specify partition information during setup Express will create a C partition with the maximum amount of disk space available You are prompted to automatical
5. Tab From the Source tab change the restore from List to Restore by Tape 14 Click the to expand the tape sessions on the selected tape as shown in Figure 14 Si ARCserve Restore Untitled 1 BEE f amp amp File Manager View Restore Window Help 18 x B bors sos A Rie Source Destination Schedule E Restore by Tape B A 03 04 98 2 22PM ID 3B4C Bl m Session 0013 DCH1T200 C 03 04 38 2 22PM Session 0014 NNDCH1T200ND 3B4C Session 0015 DCH1T 200 F 1 T 15 3 17 88 3 40PM F H 0 E Session Method Session Flags Drive Catalog No Detail KBytes 52 295 Files 498 I My Computer DCH1T200 User Administrator 3 17 88 4 54 PM 7 Figure 14 Restore Manager Window Tape Sessions Click the green box next to the most recent session for the F drive that you want to restore Click the Destination tab Figure 15 By default the Restore files to their original location s should be checked check it if it is not Sy ARCserve Restore Untitled 1 Of x fs Eile Manager View Restore Window Help i81 x Bl pciraoo oooQ al a s Source Destination Schedule IV Restore files to their original location s original Location gt Destination zl x Restore files to their original location s My Cemputer DCH1T200 User Administrator 3 17 98 4 54 PM 7A Figure 15 R
6. 02MB partition and press Enter to install Windows NT on that partition You are prompted to format the partition as either FAT or NTFS 9 Select FAT default and press Enter to format the drive You are prompted to insert the Cheyenne Disaster Recovery Diskette Insert Recovery Disk 1 Insert the Cheyenne Disaster Recovery Disk cheydr04 dsk image diskette Press Enter to continue File copy will now begin You will be prompted when the file copy process completes to remove any diskette and CD ROM from the drives Remove the Windows NT CD ROM and the Cheyenne Disaster Recovery Diskette Press Enter to reboot the server The server reboots At this time there should be a locally attached tape device installed with the current full backup of the system inserted in the drive The Cheyenne disaster recovery wizard is displayed Figure 1 Cheyenne Disaster Recovery Wizard ii Es Welcome to the Cheyenne Disaster Recover Wizard The Wizard will quide you step by step to recover jour system If you previously saved pour computers configuration cn a floppy dick you ean retrieve it new by insstting the floppy disk iito dive and pressing View Config bution lt Back New gt Cancel Figure 1 Cheyenne Disaster Recovery Wizard Confirm that the current full backup tape is inserted into the tape drive Click Next to continue The Tap
7. Writing Technical Instructions Note This article originally written for online Written Communication students The Wall Street Journal said that 80 percent of businesses surveyed believe that their employees biggest problem is written communication It is written that manufacturers of sophisticated products have not been successful with gaining a good customer base because of returns of the products The products were returned because the customers could not understand the instruction manuals although there was nothing wrong with the products Some of you will write or be responsible for instructions and procedures as part of your work Here is something that comes to mind that may be helpful We can desire to write clearly but many times remind myself to write procedures so that they cannot possibly be misunderstood That s saying a lot but it s the attitude that is important to take when writing procedures for a specified audience What may be clear to the writer is not necessarily clear to the audience The writer will first make sure that he she analyses the audience write and organize the procedures for the audience present the procedures in an appropriate format and then test the instructions or procedures with a representative sample of the audience and make revisions until the instructions or procedures work for the audience have found that a lot of instructions and procedures look good they are signed off by those who do not
8. communication techniques that must be used in order for the manual to achieve its purpose have observed that where quality documentation is considered very important those managers responsible for seeing that it gets done have been promoted at a faster rate than others This causes me to advise all students to not underestimate the value of quality documentation and effective written communication In writing technical documentation for Systems Engineers have been proud to produce quality documentation for intranet access Throughout the country the engineers were able to use the documentation from a laptop with good results Writing instructions is a very valuable skill especially when the users find that the instructions you write are easy to follow and really work When writing instructions here is a pattern that find to be very effective Start with a paragraph that outlines what is to be accomplished in a procedure and list the objectives Number each step to be performed by the reader This may be referred to as an action step After each action step describe what the reader will see or what the result s will be while always making sure that there is only one action step per number as follows 1 The first action step Describe what is to be done by the reader In the same step describe what the reader will see or what the result s will be 2 The next action step Describe what is to be done by the reader In the same
9. dialog box You are returned to the Disk Administrator window 10 Close the Disk Administrator window You are returned to the Windows Desktop Restore Data 1 The data from the F drive needs to be restored to the partition This section assumes ARCserve 6 0 is installed see later section for instructions on ARCserve 6 5 From the Start Menu select Programs gt ARCserve for Windows NT gt ARCserve Manager The Quick Access menu is displayed Figure 12 Quick Access x Job Status Media Pool Management Global ARCserve servers jobs and ee Media pools and media configuration activities management Backup ca Device Management EX Custom and automated backup of Real time format erase and status networks display of tape devices Y Restore Database 7 Complete data recovery of volumes All Manage and view the Database directories and files obs Tapes etc B8 Eo el A a S i Recover DB Merge Tape Scan Tape Compare Count Purge Figure 12 Quick Access Menu Click on the Restore button The Restore manager window is displayed Figure 13 EEUU STI Of x 1 File Manager View Restore Window Help 18 x ema 333 Source Destination Schedule Restore by Tape zd 03 04 98 2 22PM ID 3B4C I My Computer DCH1T 200 User Administrator 3 17 88 4 54 PM pA Figure 13 Restore Manager Window Source
10. e devices and media dialog is displayed Figure 2 This will show you all locally attached tape devices that were detected and any media that is in the device _ 7 Cheyenne Disaster Recovery Wizard Figure 2 Cheyenne Recovery Wizard Showing System Tape Devices and Media If the dialog shows the proper tape and device click Next to continue The tape session dialog is displayed Figure 3 Figure 3 Wizard with Tape Session Dialog Displayed Scan Tape For Backup Sessions 1 Click the scan tape button to scan the tape for all backup sessions This will take a few minutes 2 After the scan Is complete confirm that the correct sessions were detected Figure 4 Figure 4 Wizard with Detected Session Displayed 3 Click Next to continue The session assignment dialog is displayed The purpose of this dialog is to assign the detected backup sessions to the appropriate disk drive and then proceed with the restore process 4 Left click on the Unformatted 1502MB partition to select it 5 Click the Drive Letter button The Drive Letter Assignment dialog is displayed 6 Click Assign drive letter and select D 7 Click OK to continue You are returned to the session assignment dialog 8 Left click once on the C partition 502MB to select it 9 Next click the Assign button This will open the list of session
11. e selected partitions and select Create Volume Set 3 A dialog is displayed prompting for the amount of disk space to allocate to the volume set Figure 6 Minimum total size for the volume set is 2 MB Maximum total size for the volume set is 6148 MB Create volume set of total size Figure 6 Create Volume Set Dialog 4 Accept Create volume set of total size default all available disk space and press Enter to continue Format Volume Set 1 Right click on the newly created volume set and click on the Commit Changes Now menu option Three messages are displayed The Confirm window Figure 7 prompts you that the disk configuration has changed click Yes to save the changes Q Changes have been made to your disk configuration Do you want to save the changes Yes F Ho Cancel Figure 7 Confirm Window 11 The Disk Administrator message 1 Figure 8 informs you that disks were updated successfully and you need to update the repair disk click OK Disk Administrator xi Ci Disks were updated successfully It is recommended that you update the emergency repair configuration information and create a new Emergency Repair Disk You can do this with the system utility RDISK EXE Figure 8 Disk Administrator Message 1 The Disk Administrator Message 2 Figure 9 informs you that the partition information has changed and you need to update the boot ini file
12. estore Manager Window Destination Tab Click the Schedule tab The default is Run Now is displayed 15 From the Restore menu select Run Schedule The session user name and password dialog is displayed Figure 16 For each tape session enter Usemame and password for the machine to which the files are restored Figure 16 Session User Name and Password If you are logged on as an Administrator equivalent you will not need to change any information click OK to continue If you are not logged on as an Administrator equivalent click the session to select it and click Edit A dialog will appear prompting you to enter a user name and password 10 A summary dialog is displayed Figure 17 r Job Description DK nae ok Restore Run Now Job Lotes Destination Node Restore files to their original location s swe Help uiuia iat Description Figure 17 Summary Dialog 16 11 Click OK to continue if all the information is correct The Restore process will begin Figure 18 ine ee ae aba zeli i SS S 9 s e tl d Wy Gorpua c DCHT2 Jeb Queue sci Les i 000 7 fler Admirina 0 anie di m 00 Figure 18 Job Status Window 12 After the restore has completed a Job Status Window is displayed with the status of the restore job indicated Figure 19 5 Restore Operation Successful Figure 19 Restore Operati
13. instructions It is only an example of a formatted technical manual as explained in this article Actual content is not necessarily meant to be accurate The Appendix of the Operational Recovery document is a list and description of Computer Systems Document Types The last item listed is the Operational Recovery Document James Barakaat aka James Graves Barakaat of http JamesGraves com Operational Recovery for Windows NT Table of Contents Procedure for Locally Connected Tape Device Create Disaster Diskettes Insert Installation CD ROM Insert Recovery DISK deos ied ep Scan Tape For Backup Sessions Start Disaster Re cOVOLy i oo Rb ee Create Volume Seti cioe pct Format Volume Set esses Restore Datari eite diruit er ative de ADpenDlX oin eite ttti tete e Ere ete Computer System Documentation Types Purpose This document will detail the steps required to recover a Windows NT server from a complete failure The following assumptions are made in this document There is a current full backup of the system Arcserve 6 x or higher There is a tape device locally connected OR There is a tape device network connected The Windows NT Server setup CD ROM OR A Windows NT Server distribution CD ROM Audience The audience for this topic is any individual assigned the responsibility of performing this procedure
14. ly scan for mass storage devices or specify your own 6 Press Enter to automatically detect You are prompted to insert the Windows NT Server setup disk 3 7 Insert the Windows NT Server setup disk 3 cheydr03 dsk image diskette After the hardware detection is complete a list of mass storage devices that have been detected is displayed 8 Press Enter to continue You are shown a list of hardware video mouse etc that setup has detected Do not change the settings 9 Press Enter to continue You are prompted to insert the Windows NT Server CD ROM Insert Installation CD ROM Insert the installation CD ROM for Windows NT 2 Press Enter to continue You are prompted to specify a destination for the files to be installed Create the C and D drive partitions as follows 3 Select using 11 keys the Unpartitioned Space line and press C to create a partition You will be prompted to enter the size of the partition to create by default setup will enter the maximum available space to the partition 4 Use Backspace key to erase default amount 4044 and enter 502 5 Press Enter to continue You are returned to the previous selection screen 6 Again select the unpartitioned space and press C to create another partition This partition will be 1502 in size 7 Press Enter to continue You are returned to the previous selection screen 8 Select the C 5
15. on Successful Window 13 Close ARCserve 14 From the Start Menu select Shutdown gt Restart the computer 15 Click OK to complete the restore process 17 Appendix Computer System Documentation Types These are some of the main documents involved in information systems RA FS TS PC IN IM Documentation Type Requirements Analysis Functional Specifications Technical Specifications Programming and Coding Integration and Testing Implementation and Testing Description This document describes what the system must do in order to perform the business functions of concern It basically describes features and benefits of the system why the system should exist who will use it where it is to be used when it is to be used and how it fits into the business as a tool to solve the business problem Information is usually gathered by interviews This document describes what the input screens and output screens must look like in conformance with the Business Requirements Analysis It includes the format of the screen design menu items the output forms the type of storage and the processing required to produce the outputs from designated inputs specified by RA This document describes what hardware and software must be used to design the input screens perform the processing and produce the output screens and reports in conformance with the Functional Specifications This desc
16. provides the instructions for backing up storing and recovering data 19
17. ribes the programming language software and the hardware required to satisfy FS It includes the System Architecture that includes the type of database program Sybase Oracle SQL Server etc Network Configuration and connections among other things This documentation includes the algorithms pseudocode flowcharts and the actual coding in conformance with the Technical Design Specifications The program using the specified program languages is designed and coded to function as required in FS This document describes the hardware and software that is used with the basic system It also describes how the other software and hardware that is to operate with the main system is integrated and tested with the main system This document describes the system installation and test procedures using test data 18 Documentation Type UD CM OR User Documentation Configuration Management Audit and Change Control Operational Recovery Description A User s Guide is used to guide the end user in the operation of the system A Program Developer s Guide and an Administrator s Guide may also be put in this category This documentation describes how to control and document the functional and physical characteristics of software or hardware It also documents the control of the changes to the characteristics and the recording and reporting of the change processing and implementation status This guide
18. s that were found on the tape 10 Click on the backup session of the C drive to be restored 11 Click OK to continue You are returned to the session assignment dialog 12 Left click once on the D partition 1502MB and click the Assign button 13 Left click once on the backup session of the D drive that you want to restore 14 Click OK to continue You are returned to the session assignment dialog 15 Click the Next button to continue The Start disaster recovery dialog is displayed Start Disaster Recovery 1 Click the Start Disaster Recovery button to begin the restore process A dialog is displayed stating that you need to restart the machine 2 Click OK The server will reboot After the reboot the restore wizard automatically starts restore process Wait patiently 3 When the restore process completes look for a message at the top in the restore wizard stating that the restore finished successfully 4 Click Finish A dialog is displayed If you restored Windows NT system to a partition which is physically different than the partition it was located originally you need to modify the corresponding entries of boot ini Do you wish to modify it now 5 Click Yes to continue Confirm that the boot ini that is opened looks exactly as listed below make changes accordingly boot ini file boot loader timeout 5 default multi 0 disk 0 rdisk 0 partition 4 WINNT
19. use the procedures and when they don t work the user needs help which can result in loss of time and resources Just because writers know how to string sentences and paragraphs together doesn t mean that the writing should not be tested for usability Developing a user s manual can be most critical especially in a virtual situation Many of us can string sentences and paragraphs together and make a document look good When we analyze our audience find out how users will use the information in the manual consider the best presentation and then revise and test the manual for usability we can produce a manual that works When a manual does not work for the user they are usually prevented from doing what they are supposed to do We then end up using trainers developers technicians or other subject matter experts to help do what the manual should do This adds to the overall cost in instructing the user When writing a manual for a technical person the technical person can work through the presentation because of their knowledge regardless of the quality of the manual Still a quality manual will save them time When approach the writing of a technical manual take the attitude that will write such that the instructions cannot possibly be misunderstood While this may never happen it causes me to do a better job in producing a manual that works While a lot is learned about the subject of the manual it is important to recognize the
Download Pdf Manuals
Related Search