1 Technical & Business Writing (ENG-315) Muhammad Bilal Bashir UIIT, Rawalpindi

Outline 1. Guidelines for Planning a Documentation Project 1. Start the Project 2. Perform the User Analysis 3. Design the Documentation 2. Summary 2

Planning and Writing Your Documents Lecture: 15 3

Guidelines for Planning a Documentation Project The documentation process 1. Start the Project 2. Perform the User Analysis 3. Design the Documentation 4. Plan the Documentation Project 5. Write the Alpha Draft 6. Conduct Reviews and Tests 7. Revise and Edit 8. Write the Final Draft 9. Conduct a Field Evaluation 4

1. Start the Project Most software and software documentation is created by two kinds of teams:  The development team  The writing team The essential difference between them is that on development team you work as writer or editor with professionals who do the programming, planning and marketing the product. Its is also called cross- functional team On the other hand, in writing team consist primarily of people who write, edit or test documents 5

Start the Project (Continue…) The Development Team  Develops the entire product (software and documentation)  Different kinds of professional presents in this team with their distinct responsibilities and skills Product Developer Project Manager Market/System Analyst Technical Specialist/ Programmer Documentation Specialist 6

Start the Project (Continue…) The Writing Team  Develop just the documents  Develops documents of more than one project at a time  The team members usually belongs to the same background  They have to deal with developers, programmers and other involved in the project Manager Lead Writer Writer Editor Graphics Designer Tester 7

Preliminary Research The developer or the market analyst do the preliminary research by examining the user and the industry for determining the need of the software (justification of software project) The research includes the following documents  Project Plans Identify the long and short term goals and justification for the project itself  Program specifications Describes the nuts and bolts of program to be created to meet the goals of project plan 8

Preliminary Research (Continue…) The research includes the following documents (Continue…)  Market Analysis Represents the market specialist report into the sales and market potential of the software system  Information Plan Identifies the kind of document needed by program users.  Management Plan. Provides the details of the resources, people and schedule for completing the project. Represents the day by day strategy for completing the project 9

Overview of the Online Help Development Process An online help system is a document that is delivered as software using the stand-alone WinHelp format, an HTML format, or PDF format The stages of developing an online help system  User Analysis Needs to focus on workplace activities of users User need some sense of help system and technical knowledge  Mastering the Authoring Environment It is computer program that allows you to create a help system  Linking the Software Program Required to use special codes so that when the user calls the help within program, it must respond with the appropriate help topic 10

Overview of the Online Help Development Process (Continue…) The stages of developing an online help system (Continue…)  Testing the Help system Required to test the links as well as contents  Testing in Different User Environment Online help system need to work across computer platforms (Windows, Macintosh, Linux, Unix etc) 11

Starting a Help Project Selection of Right Authoring Environment Single Source Capabilities  Write your help topics once and can use them in different formats easily Management Features  Ability to plan and keep track of project Types of Help Formats Supported  Word document or PDF  Windows Help  HTML, XHTML, Microsoft HTML Help  Java Help 12

2. Perform the User Analysis The user analysis results in list of activities for each of the primary users of the program, which in turn allow you to identify which of the program operations the user would need The user analysis is key to the table of contents of your manual and help The activities in user analysis should allow you to group the program operations for your table of contents 13

3. Design the Documentation During the design phase you apply the three types of document forms- tutorial, procedure, references The design phase also includes documentation outline and decision about the layout: pages, text style, size, font and language For online help you need to decide on types of products you will produce (help. Training, guided tour, template, messages, tips etc) Make a detailed list of help topics and determine their layouts 14

15 Summary Any Questions?