 Lecture 33, Assalamu Alaikum. Welcome to the virtual university's course on business and technical communication. In today's lecture, we will look at writing specifications and analysis reports. Today, we will examine the different types of specifications common to the computer industry. Then, we will examine the importance and main features of analysis reports. We will also see that terms and conventions often differ from company to company, but that the general framework is similar. For everyone involved in the design phase of the computer industry, hardware engineers, software engineers, technicians and programmers, specifications are the most important document to be read or written. The audience for specifications is highly technical, but that does not mean that the audience necessarily shares the knowledge of the writer. In the computer industry, specifications are very important for anyone involved in the design phase of the computer industry. The people who read the specifications, the readers of the specifications are also very technical and those who write are also very technical, but that does not mean that the readers have all the knowledge that the writers have. Both have technical expertise, but they have their own level and scope. So, the readers will have a special difference in their technical expertise. And this is particularly true when specifications cross major professional lines within the computer industry. For example, a specification might be written by marketing people for hardware engineers or even by hardware engineers for software engineers. Now, all these technical experts are related to the sub-computer industry in their field, but they are experts in their field. So, the people who are writing about their sub-computer industry and the people who are reading about the sub-computer industry in their field, it is not necessary that both have technical expertise as much as they do. So, while writing, make sure that the people you are writing, the readers do not have exactly that level of expertise, they are experts in something else. Even though the language of specifications is precise and the treatment of the subject is thorough, great care must be taken to ensure that the specifications can be used by the intended audience. Because nothing wastes more time in an organization than having to figure out a poorly written specification. The situation is even worse when work has to be undone or redone because the specifications were bad. Specifications can be categorized into four types. There are requirement specifications, functional specifications, design specifications, and test specifications. Although the names of these specifications differ from company to company, some companies do not use the same names of different specifications in each company. But, we get four types of specifications in each company. Computer products are designed, produced or marketed. So, all companies which are designing, producing and marketing a computer product will be using each of these four types of specifications or specs as we can call them for short. Let's have a look at requirement specifications. We will look at the first requirement specifications because this is the first step in the design phase of a new product or if we are updating or changing the existing product then we need requirement specifications. So, as the first step in the design phase, requirement specifications become very, very essential. People in the marketing division of a company are responsible for determining what the market desires and depending on the desires of the market, depending on the requirements of the market, these market specifications are then laid down. The result of market research is requirement specifications. In these specifications, the marketing people attempt to specify what the market is looking for, what people or companies who use computers would find useful and what they would like to have. So, based on the research that the marketing department does, they determine what the need is and then they specify that need in terms of specifics so that the product can actually be developed according to what the people who will use it, what the companies who will use it actually desire. Because marketing people are not design engineers, requirement specifications are at best general. The marketing people can do no more than provide in the requirement specifications. The marketing's best effort to describe what would be a profitable product. The marketing people through the requirement specifications can tell what would be a profitable product. The marketing people through the requirement specifications can tell what would be the best product, but the scientific details of it cannot be described in the requirement specifications. Requirement specifications basically provide the design groups with a place to start. Those who want to design, they get a starting point that this is a business, now we will make and design it according to that. Often, requirement specs will contain enough information so that readers can see relationships to past technology. The requirement specs will provide such information that the first products were used in the market and the first technology was the need and desire of the people. So, the last technology and the last work in the field will also establish a relationship. In order to do this, requirement specifications should contain the following. They should have a product definition. This product definition is an accurate description that is written by the marketing people about the desired product. The more accurate description they can give, the more accurate marketing people should give them so that the people who design know what the market needs. It should answer the question, what is it? The question is, what are the things that people are looking for? So, the marketing people need to define what the product needs to be. Then, they should also include functions list. This is a description of what the desired product should be capable of doing. These are the functions which this product can do. First, we will tell what the product is and then we will tell what the product will do. And this then leads to the next type of specification. The other specification that will be needed in requirement specification will be the cost. This is a ballpark estimate as to what the desired product should cost to be competitive in the market place. Obviously, the marketing people have researched and they have seen which products are available in the market, which are similar to this or which products can be made new. When they research, they will also see the cost of their products or the price of their products. Then, they will also tell that the new product should be this and that it should be around this price so that it will be competitive in the market and then it will sell. And then we move to the functional specifications. In most organizations, the requirement specifications lead to the formation of a group to study the desired product. When the requirement specifications marketing department is given then a group of people will sit and study the product. They will see what it is and how it can be made and what it can do. The requirements specifications that were written and asked whether they can be completed or not. This study in the computer industry is usually broken down into hardware functions and software functions. And it leads to both hardware and software functional specifications. The people who will study this product will see the hardware and software functions that what this product can do and what are the hardware and software functions and their functional specifications will be written. Then these functional specs will form the basis for the highly precise design specifications. Once these functional specifications are written then the design specifications will be written. Functional specifications like we said hardware and software functional specifications will be divided. Hardware functional specifications as a rule contain a functional description of the product. This functional description of the product is a precise description of the purpose, use and operation of the product. The functional description of the hardware of the product is the purpose, use and operation of the hardware. Also these hardware functional specifications will deal with the configuration specifications. They will include configuration specifications which will specify such things as how the products components are to be interfaced with each other the different parts of the product what will be the interface between the hardware parts and with other available products. Then they will also deal with the electrical description. This part of the specification describes the electronics which will be used to accomplish the product's capabilities which are the electronics which will be used so that they work according to their capabilities. The hardware functional specs will deal with the physical characteristics which will be a precise description of each of the product's components which are a detailed description of the product. The standards will specify how the desired product should fit into existing company standards and environmental requirements will be a description of how the product will be used and under what conditions. We will also have diagnostic requirements and power requirements which will describe what sort of power source will be most likely to be used in the new product to run it. We will have a cost target that what are the costs of the customer and the consumer. As we have discussed, the cost will be mentioned in the requirement specifications but it will be only the desired cost. And in the functional specifications we will also have a maintenance cost target. This establishes what the expected maintenance costs are likely to be per month. We will also have resource requirements. This specifies what resources will be needed to design the product. When a product is designed, it will require a lot of things. It will require a lot of equipment. It will require a lot of equipment. It will require a lot of equipment. It will require a lot of equipment. It will require a lot of equipment. It will require a lot of equipment. It will require a lot of equipment. These are all resources. In the hardware function specifications, we will also have resource requirements. And also documentation will be specified. This will outline the necessary documentation for the product. What are the documents that are required for the product? Depending on the product and its uses. There will be many things. Usually including the manuals which will accompany the product. We talked about it a few lectures ago. Instruction manuals. This is a very major document which goes with the products. Similarly, if there is any documentation which will have to be developed with a product, it will also be mentioned that this is also a part of the hardware. Then the specifications will also indicate the risks which will be a discussion of the risks inherent in pursuing the design, the development of the product and the marketing of the product. What are the things which are expected to be wrong when we design and develop this product and market it? They will also be discussed first. In the functional specifications it will be mentioned that we are making this product but if there is any indication that it is wrong, then it should be mentioned first so that the person who makes it should keep an eye on it. And any assumptions which will describe any underlying assumptions which can be made about the product and process of designing, developing and marketing it. There are some assumptions about something which will be based on the product and the market and on that those assumptions will be written in the functional specifications. The functional specifications will also deal with any unresolved issues even in documents which are very thorough, like these specifications there will be issues which will remain unresolved. And if this applies the issues should be presented and discussed. Those who are writing the specifications feel that they are but they have not yet made a decision they should also be mentioned. And then a glossary which is a list which tells about terms which may be potentially unfamiliar to the readers. This is to ensure that readers can understand and use the specifications. Any difficult terminology or terminology which may not be known to the readers will be given a list at the end of the specs so that users can use those specs in the right way. This was the hardware functional specifications. The second thing we will see software functional specifications are similar to hardware functional specifications but there are some differences and we will talk about those. Now when we are talking about software functional specifications I will not be explaining those specifications which are common to hardware specifications. The things which are hardware or software functional specs are common I will not repeat them again but the things which are software functional specs require extra I will mention in detail. Software functional specs usually contain a functional description of the product product features which will describe the capabilities of the product in detail. Dependencies which is an elaboration implementation and use of the software will depend upon physical characteristics which as we have talked about hardware specs risks, assumptions cost targets, maintenance cost targets, resources documentation and glossary. Obviously the level of detail increases dramatically between requirement specifications and functional specifications because the requirement specifications as we have mentioned are written by marketing people they are not that specific they are not that technical after that functional specifications are a little more technical and all the functions are described by a product. And then the design specifications are more specific than this and more detailed than this. Design specifications are then based on functional specifications. Obviously when functional specifications are written after that a product starts to be designed that these are the functions then we have to design those functions The goal of design specs is to provide a detailed design of each of the product features the features and all the details of the design are given in design specifications and these specifications are written while the design process is ongoing. Design specifications are later used as the basis for test plans and used as the basis for testing test plans and user documentation. Hardware design specifications generally contain some versions of the following components they contain an introduction which should be a three part purpose statement introduction which explains the need for the product lists the specific features of the product and forecasts the contents and use of the design specification The introduction of the design specification will fulfil three purposes First of all it will explain the need for the product then it will tell which specific features will be in the product and it will forecast users or contents It will also have a section on applicable documents There is a list of documents which contain information pertinent to the product There will be a list of the documents which will be used for the product Such a list is absolutely essential to the technical writers who will be producing the documentation manuals for the product The technical writers who will make the documentation manuals the details of the documents then design specifications will also include functional description of the product and this section which talks of the functional description will be a detailed description of the functions of the product as a parent from the name what the product is designed to do and how it is designed to do it What are the functions of the product and what can the product do The design will be done for what and how it will be done We will also talk about external interfaces a section which will specify all the interfaces which apply to the product and we will also talk about the detailed design of the product This section will be in detail with specifications about the design of individual aspects of the product functions The different functions of the product will be explained in detail and this section will be the most detailed section of the design specifications The other sections will be smaller but the detailed design is the most important because we are talking about the design so we will give the most time and space to this section We will also talk about programming considerations and in this section we will describe all aspects of the hardware with which a programmer would come into contact Obviously when a programmer designs something the hardware will also be explained in detail We will talk of power requirements we will talk of reliability which will talk about how reliable the product that is designed will be and what is expected of it with regard to service and maintenance how it will be maintained and if we maintain it we can expect it how much life we can expect what kind of work we can expect and how reliable it will be We will then talk of as we did in functional specifications we will talk of diagnostic considerations standards, environmental requirements and we will have a glossary Now the software design specifications is also similar to the hardware design specifications As we saw in the functional specs software design software functional specs and hardware functional specs Similarly in design specs software design specs and hardware design specs because both the things will be designed hardware and software will also be designed as we did earlier the differences in hardware and software design specs now we will just discuss them as you saw in the software design specs now we will look at the software design specs which are not in the hardware design we will look at the additional remember that the software design specifications are used for testing and technical writers use it for user documentation and to meet these two purposes of using the software design specs and for user documentation the software design specs should contain an introduction they should have a description of the applicable documents like the hardware design specs and they should have a functional description which will be subdivided into however many functional features the software has if there are more functional features then there will be different discussions then there will be discussion of the general design this section will detail the way in which the software design objectives are met again hardware design specs will be detailed software design specs and it will include such material as data structures data flow, program relationships etc we will then have memory requirements, performance and restrictions this is a section which we discussed about the hardware design but in software design specs we will include it and this section will detail how the software fits into and uses computer memory also it assesses the performance of the software and the restrictions which might apply the performance of the software will tell how it will perform and how it cannot perform this will also be told we will also list any product requirements which will discuss such matters as security, usability installation and maintenance requirements we will talk about a test strategy and in this section we will present any helpful suggestions that could be used in developing a test plan for the software obviously any software will be tested for that any strategies will be told in this section then we will talk about any deviations from functional specifications obviously design specifications are made on the basis of functional specifications then there will be a section which you are changing from functional specs you are changing some deviations will be mentioned then we will talk about interfaces as you said for hardware and if necessary then we will include the glossary the user documentation of any computer product generally people complain that it is unreadable because it is so complicated but if the computer professionals take some time and write design specifications thoroughly keep an eye on the audience who are technical writers who want to use the users of the computer keep an eye on them and then present the design specifications then the user documentation will be improved so design specifications are very important to be clearly written clearly written because by looking at them technical writers will make the product and the users will use the product now coming to the final specifications that you will be writing in a computer company test specifications before a product can be marketed it must be tested you first got requirements specs functional specs design specs now you have designed the product but before marketing it you have to test it for that you need test specifications and on their basis you will see how this product will perform in market conditions this procedure should be specified consistently across a company and test specifications should contain the following as a guideline test specifications should have an introduction like all other specs it should have a discussion of applicable documents those documents might describe test procedures on similar products which have been designed and developed in the past whatever discussion there is of products and tests that have been done on other products will be included in this discussion of applicable documents there will be a description of the unit to be tested the unit to be tested there will be a discussion of the testing method in which there will be a step by step description of the testing procedure also very importantly there will be a section on precautions this section will detail any special care that must be taken in the testing place when you are testing a product what are the things that you have to keep in mind what are the precautions that people are testing it is very important to mention that do not do this otherwise this product will get spoiled and the same degree of precautions apply here as they do for procedures so you will apply the same degree of caution as you will when you are actually using the product when you are actually putting that product into place and then there will be a glossary again as we have seen in other specs if you need a glossary there are any technical terms which are used their details will be written so that the specs are easy to understand the specs now this is the product specifications the second thing we have to see in today's lecture is analysis reports analysis reports are called by different names from company to company people call them formal reports project reports, final reports job ending reports etc these reports are an important aspect of documentation within the computer industry the important thing to remember is that no report format is perfect if you have a report format it is not perfect that it is used in every situation so remember according to your needs according to your product according to your company and according to every purpose the format of the report will change company documentation standards attempt to resolve the issue of finding the perfect report format by prescribing a format into which all analysis reports are poured many times companies give one format and put it into the same format but the report design should be so flexible that it can meet different purposes if you have to write all kinds of reports in just one format then many things will miss out so the report design should be flexible enough to meet a variety of writer purposes and a variety of audience the proper report should be designed with visual order in mind it should be balanced from top to bottom and from left to right and it should provide enough information for readers to be able to tell what the context of the report is and what the report is about whatever analysis report you are writing from its title you should know what is written in this context also titles should be kept relatively short they should be no more than 10 to 12 words there is no use of long titles because they are against understanding titles should be written in 10 to 12 words so that the readers can see it immediately and understand what analysis report is about if the title is in two parts if it is a two part title then it can be a little longer because when you divide something in two parts then it becomes easy to understand then you should make it a little longer still it will not be against understanding because it has already been divided in two parts two part titles are fairly useful because the first part is general providing the context the second part is specific indicating the main point of the report and or the most important aspect of what was done whatever work is done which is being analysed in the second part the second part of the title the main point is given or the most important aspect is mentioned whereas in the first part the most important information is what is the report in analysis reports we have abstracts abstracts are condensations of entire reports and they focus on main issues they focus on what was done what was found out and the significance of that you have to remember that abstracts should be self-sufficient you should understand what was in the whole report then after abstracts nothing else should be needed the procedure for many companies is to take the abstract from the analysis report copy it a number of times circulate it to different readers and allow readers to order the full report if they feel that they need the information on the basis of an abstract the audience gets to know if we want to read the whole report we copy it to different readers and then people understand that this report is our job then we order that report let's have a look at an example of an informative abstract plot file is a program written for concord sciences corporation as a solution to the graphic problems specifications were made by the president of the company and followed with two exceptions the program now in use also has features the user provides information through interactive commands on a video display terminal to specify desired plotting formats with flexible logarithmic and linear capabilities the program then draws the desired axis or grids and plots the sets of points read from the data file now in this abstract we get to know what is in the report now the people who want to read the report will order the report another thing that is important to include in analysis reports is the table of contents the table of contents provides an outline of analysis reports for readers who do not wish to read the entire report or for readers who do not wish to flip through it looking for sections which contain what they are looking for as you may have seen in the books there is a table of contents and the entries correspond to the entries in the book similarly in your analysis reports there will be a table of contents and all the headings and sub-headings will correspond to the headings and sub-headings given in the analysis report they will be word to word the same and they will have accompanying page numbers you will also have a list of symbols but this is an optional addition to the front matter of an analysis report you will include a list of symbols if you think the readers will need to have symbols defined and the same thing applies to the inclusion of a glossary now after all these this front matter you will have the introduction this is the place for the three-part purpose statement introduction it will orient readers to the main issue of the report to the technical issues or specifics which are important to the report to what the report is intended to accomplish after the introduction you will have the discussion which will contain an analysis of the technical issues of the report in the introduction you just told that we will discuss these issues in the discussion you will also support the main idea to the report by providing evidence and explanations the main idea you will include in the discussion your discussion should be subdivided into topics of a sub-heading after the discussion you will have the conclusion this section will present the results of the analysis the result will come in the conclusion the evaluation of what is presented in the discussion will be part of the conclusion in the discussion the evaluation will be written in the conclusion sometimes listing the conclusion is a good way to organize them you can also point by point because the reader can easily get all the concluding points also listing calls attention to each conclusion individually and it still enables writers to explain them as necessary if you point them one by one then the reader can see a different point and if you want to explain the point then they can do it the recommendations section is optional not all analysis have recommendations those reports that do have recommendations tell the readers what to do with the information that is provided in the report it is not necessary that every analysis report has recommendations they will tell you what to do with the information that was provided in the report you can have appendices in your analysis report but you have to remember that appendices are not the dumping ground for material that is left over they serve a precise purpose don't think that whatever you can use in the report can be used in the appendix there is no such thing whatever you can use in the appendix there should be recommendations if there is information which is not vital to understanding the main and technical issues of an analysis report it can be placed in an appendix for purposes of documentation if you think that there are some things that you have used but it is not necessary to include them in the main part because without them the main discussion can be understood still it is important but it is not so important that you are against understanding then you can include those things in the appendix usually these kind of things would include derivations of equations tables of raw data sample equations and so on the things you want to show to the audience but without seeing them the only way to be certain that what you have included in the appendix actually belongs there is to assess the audience's needs don't keep yourself in the middle keep your students in the middle and think how much they need if it is essential then keep it in the main section if it is less essential but you want to show that this information is used or you have collected then keep it in the appendix in this lecture we have learnt about the different types of specifications which are common to the computer industry we have examined the importance and main features of analysis reports and we have also seen that terms and conventions often differ from company to company but the general framework is the same so now after this discussion specifications and analysis reports discussions we will end today's lecture until next time Allah Hafiz