Engl477technicaldocumentationpoliciesandprocedures

Barker Ch 14

2006-11-27T13:14:00.000-08:00

Chapter 14 - Designing Indexes

When I read this chapter I thought of my English 475 Technical Editing class where Dr. Nord told us, "Indexers make a substantial amount of money...probably because no one wants to do that job!" Barker did a good job making the indexing task look less tedious than it actually is, but still showed how detailed the procedure can be.

Barker does mention that indexing can be very redundant work, but he says it's usually we don't realize how important this work truly is. He says that indexing performs a uniqute function by directing users straight to the material in the manual, therefore it is one of the most important functions. It also is the meeting place of multiple users, meaning that all users can find the terms they use and be directed to the information they need.

Campbell Chapter 12

2006-11-27T12:22:00.000-08:00

Chapter 12 is about online documentation. It points out that going online with documents will not make them easier for people to understand; it's just an alternate form of delivering your document(s). It lists advantages and disadvantages with going online. Some of the advantages listed are being more efficient than the paper system, delivering the message instantly, less costly to maintain, and save storage space. Some of the disadvantages that are listed are that people who are not comfortable with computers may go back to paper copies, it may require a significant budget, and readability is less than that of a paper document. The chapter also lists some online design considerations.

I think a good example of going online would be the process of registering for classes at MSU. Students used to be able to register on paper or online, but it has changed to online only. Some people might find it much easier, but others who are not familiar with the process may find it problematic.

Barker Chapter 13

2006-11-27T06:48:00.000-08:00

This chapter teaches us how to use graphics effectively. If Phillip VanWynGarden would have read this chapter, we wouldn't have had as much work to do on our usability project.

While there was a lot of information covered in this chapter, one of the more important topics covered is under the "Where Is It?" heading on page 408. When I read the section about showing the user where to look to perform tasks, I couldn't help but remember our original Usability document. The large image of the motherboard wasn't clearly labeled, so the user wouldn't know where to look for help. The smaller images weren't clear enough for the user either - I thought they were too upclose for the user to even know where to look.

In the end, I think that we did a great job with our images on the Usability project. I think the image team did a great job of labeling and highlighting the images so the user could understand them.

Barker Chapter 11

2006-11-15T08:41:00.000-08:00

Barker chapter 11 is titled "Laying Out Pages and Screens", and covers various design aspects for both print layout and electronic layout.

While this may not be the most abstract chapter thusfar, it is clearly one of the most useful chapters for anyone interested in creating documents--either electronic or print. Some of the important aspects of desktop publishing this chapter covers are creating grids, pagination, margins, styles, and various other topics important to any technical communicator. Basically, everything in this chapter is a review of what gets covered in the Desktop Publishing and Technical Editing classes offered here at MSU.

One interesting part of this chapter is the information on different webpage design structures. The chapter covers a lot of details about creating internet help pages specifically, as long as other various page types.

The chapter ends with some information on creating user-friendly help pages, and is very timely with the robohelp project we're working on now.

Barker Chapter 12

2006-11-14T23:23:00.000-08:00

Barker Chapter 12 deals with proper wording and language of software documentation. This includes such practices as creating parallelism (“Opening a file, Closing a file…”), using active voice (“Press ALT + N to open a new window.” not “A new window is opened by pressing ALT + N.”), keeping wording simple, and writing about user actions rather than computer/program functions. Barker goes on to describe several ways to confuse readers such as using too many acronyms, abbreviations, and synonyms; making sentences and paragraphs too long; and either being too formal or (trying to be) too humorous. Even if your documentation is technically accurate, it won’t do users any good if they do not understand the terminology or are turned off by a poorly placed joke when looking for support.

Campbell Chapter 11

2006-11-06T11:40:00.000-08:00

In this chapter, Campbell takes a look at revising documents that have already been written. I think she brings out a good point when she says that we need to switch from development to maintenance phase. Keeping documents up to date is a constant battle. As technology, procedures, and the business environment change we need to stay on top of the documentation that supports these efforts. Out of date documentation can cause more problems than they solve.

I like how every sample document in the chapter includes a field for recording the date. I think it makes revising work a little smoother if you can put all your comments and suggestions into a timeline.

Setting dates for revision also seems like a good idea. If you’ve already scheduled the time to perform documentation revision, you won’t be scrambling to squeeze it in to an already crowded schedule when the revision needs to be done. The documentation will probably turn out much better if you have the time to do it right rather than making it a rush job.

Barker Chapter 10

2006-10-30T08:47:00.001-08:00

Designing for task orientation
Barkers chapter 10 is all about writing to meet your users specific needs. It starts out by describing different ways to organize your information to meet your users needs, and then moves on to writing to meet the user level of knowlege. Barker talks about how taking advantage of your users skill level in your subject changes how your documentation should be writen. Alot of the concepts covered by Barker I deal with every time I write some documentation I alway state who the audience is and what kinds of prior experience they should have in the Introduction to any documentation I write. For instance if I write some documentation on how to implement a wait screen for any user requested data on a web page, I would state the you should have some idea of what JavaScript is and have a fairly decent understanding of doing your own HTML coding.

2006-10-30T08:47:00.000-08:00

Campbell Chapter 10

2006-10-25T12:38:00.000-07:00

Chapter 10 is all about implementing changes and doing things differently in a company. Though resistance should be expected, Campbell recommends that you never give up, because no matter where you work you are going to encounter similar problems. She says the way to deal with problems is through early communication with negatity; the sooner it is handled the better chance you have of problem solving. Then, continue education - keep talking to people and get their input. Lastly, give final notice. Sometimes you will just have to agree to disagree with some people and they will have to learn to live with the change.

Barker Chapter 9

2006-10-24T13:29:00.000-07:00

This chapter took a look at editing. This chapter reminded me much of an editing class I took a few semesters ago and it was a good review of what I learned in that class. Things like editing plans and different types of editing were all things that the editing class covered, but one thing I liked about this chapter was how it mentioned to keep editing editing. In other words to keep other things out of the editing process that really aren't necessary for editing. Another thing that I really liked about this chapter was the reference to editing for cross culture audiences. That is something that I haven't really been exposed to, but it is a major reality in the world. Something that may be acceptable in our culture may be something that is deemed unsuitable in other cultures. I also found the idea of various languages used for cross culture writing like the Globalized, and localized languages.

Campbell Chapter 9

2006-10-19T07:40:00.000-07:00

This chapter talks about notifying users of the implemenation of policies and procedures. Notification can be done in writing, in person, or by e-mail. All of these choices have their own pros and cons.

As the book states:

Written notices are the best when audience is very large.

Personal notices are best when the subject is sensitive to users.

E-mail is best of the new policy is online.

The thing that stood out for me was how Campbell said that Managers need to be notified first. I find that to hold very true. Without notifying management first, many problems could arise:

1. With a written notice, the manager might be asked about the policy before they have even had a chance to read it.

2. Personal notices could be a problem if the management acts surprised or upset about the policy/procedure.

3. E-mail would also be bad because if an employee has a question, they are more likely to send an e-mail to their manager - and the manager might not have any other information to answer their questions.

Barker Chapter 8

2006-10-18T12:07:00.000-07:00

Chapter 8 from the Barker text is titled "Conducting Usability Tests". Immediately after looking at the first page of this chapter, I noticed that it gives tips on how to read this chapter. Then, it gives you ideas on what you should do if you're "reading to understand." I spent a few minutes contemplating my respect for the book, and what other reasons would motivate literacy--do some people just think words look pretty? Anyways...

This chapter discusses the reasons for usability testing, methods for usability testing, and goals to set for usability testing. This is particularly relevant to the class at the point of this posting, as we're just finishing the usability project.

One interesting part of the chapter was the section on objectivity. Now, I've always known it's not nice to objectify your testers, but I learned a bit more about making sure you leave bias out of your usability testing. The two main ways of unintentionally adding bias to your testing include either caring too much about the test, or rushing it and not caring enough.

I noticed that a few of the methods discussed in this chapter were implemented in our usability testing, but it also looks like there were some places our testing could improve from methods discussed. On important thing I read that I'm not sure many people think about is interpreting the data you receive from a usability test. It's good to keep in mind that there are many ways the testing can be flawed by the moods and personalities of the testers.

Campbell Chapter 8

2006-10-16T12:51:00.000-07:00

This chapter talks about the final stages of putting together a policy or procedure. These stages involve reviewing the entire document in five areas: verification, validation, editing, proofreading, and approval. This review process is quite important, however time constraints often keep them so brief that mistakes are missed that readers notice immediately. We have all been victim of having to read something that has clearly not been edited or proofread before it was published. I have trouble when I receive a document (such as a course syllabus) that is full of typos and grammatical errors. What it says to me is that the instructor didn’t take the time to clean it up and it really lowers the author’s credibility. One way to help the review process, if time permits, is to have people other than the author go over the document.

Campbell Chapter 7

2006-10-09T12:07:00.000-07:00

In chapter 7 Campell tackles some of the forgotten aspects of technical manuals. The Design Elements I thought were fairly key. Deciding on which of the elements you want to use and how to format them can help make the manual more usable and useful. I know for our in-class project we are working on an introduction and glossary. I don’t think this project would benefit much from the other elements.

We haven’t touched on the Production Elements yet, maybe that’s something we should bring up in class. I think it’s assumed that we are going to use 8 1/2” x 11”, white paper, but maybe someone has other ideas.

Again, this chapter touches on things that I often take for granted. I never give the size or color of paper any thought when writing documentation. Campbell lists a lot of things I can take back and incorporate into my own work to make it more readable and useful to the users.

Barker Chapter 7

2006-10-02T12:57:00.000-07:00

Getting Useful Reviews

This chapter is about what to do once your document is created and you want useful feedback. Many people do not even feel that reviews are beneficial, but Barker says the three purposes of reviews are: communication function, management function, and quality assurance function.

The most valuable suggestion Barker made was regarding cover letters. On page 225 he explains that when sending a document out for feedback authors should include a cover letter to help get the desired feedback. At minimum the letter should include a paragraph for each one of these things: asking for advice and comments, the necessary background information, telling the commentor how to comment, giving dates and places for return, and saying thank you.

Campbell ch 6

2006-10-02T10:30:00.000-07:00

Chapter 6 Campbell
How do I get them to read this?

This chapter centers on finding ways to get readers to read and trust your document, by applying good design creating visual appeal. The first part of getting readers to take a look at your document it hooking them, getting them to take some interest in your document in my experiences the title has been what has “hooked” the readers or gotten there interest. A clear and concise title that accurately explains what is contained in the document is what attracts the types of readers that are going to be using the documents that I write. The next part is to create visual appeal this is important because you want to easy your reader into what the document is explaining especially if it is technical in nature, like mine which is programming based. It is very important to use lots of white space when you are documenting code, lots of cluttered code will only turn a reader off and make it more difficult for them, by using lots of white space I can control how much code the reader has to take in at a given time.

Barker Chapter 6

2006-10-01T11:43:00.000-07:00

In Chapter 6 of the Barker book, we read about "Planning and Writing your Documents." Chapter 6 talks about Development teams, Writing teams, and a lot of task management. Like usual, this chapter combined a lot of common sense methods with actual ways to carry it out. I found the "Documentation Plan" section from page 207 to be very interesting. Barker says that you can carry out all of your ideas by "the power of your personality, your charismatic leadership, your gift for higher math, and your financial savvy." Or, Barker says, you can use management plans as your "genious." As long as you have a reason for your documentation plans and you set aside clear tasks for everybody - your plans will work just fine. To me, Barker is saying that even though some people may have more charisma or personality, they might not be the best at planning these processes. Form a plan and stick to it - and it will all come together in the end.

Campbell Chapter 5

2006-09-25T12:02:00.000-07:00

Campbell Chapter 5 takes a look at various formats in use for technical writing. Learning to use the right formats for the righ information is crutial for an audience as information can easily become lost or boring when in a poorly chosen format. It would be ridiculous to have to sift through a formal narrative for a process that could easily be explained in a flow chart. At my workplace this seems to happen a lot, especially when it comes to availability. The department I work in has no standard for posting availability and many times people post it in a narrative format. These notes are often confusing, or a little hard to read. This could easily be remedied by creating a chart of some kind, rather than relying on a block of text to display the information.

Barker Chapter 5

2006-09-23T16:41:00.000-07:00

This chapter covered a lot of material - it’s the longest chapter so far at 50 pages or so. Anyway, the chapter discussed mainly what information software documenters gather on users and how they go about getting this information. It was told how interviews and observation could be used to get information such as users’ needs, motivations, prior knowledge, and usage patterns. It was also noted how users go about gathering their information, and that this is necessary to take into consideration when creating documentation for them. It can’t be overstated enough - if you don’t have a clear picture of who your audience is, your end result is going to be useless to them. A comparison could be made between investigating the audience and asking a professor about what is needed for an assignment. You want to be sure to include everything they expect to see in a way that proves to them you know what you’re talking about.

Campbell Chapter 4

2006-09-18T06:27:00.000-07:00

Chapter 4 in the Campbell book talks about using too many words when writing a technical document. It talks about the difficulty the reader might have trying to figure out exactly what the document means, and says to keep it simple. Using fewer words is better than using more, unnecessary words. Using more complex words makes the document harder to read, when easier words could have been used.

I’ve had problems with this before, mainly in text books. I have a book for a class this semester that is very hard to read because of the words used and the sentence structure. It’s almost as if the author is just trying to sound smart when it could easily be worded and written in a different way. I think it would just be easier if people stuck to what the book said and didn’t use unnecessary words, hard sentence structure, etc.

Baker Ch4

2006-09-13T13:18:00.000-07:00

In Chapter 4, Baker introduces writing reference material. I can see a great value in this type of documentation. I see it every day in various contexts. I see the tellers at the bank with there flip cards attached to their monitors for deposit codes; I see a reference chart at the Information desk in the CSC; I run into job aides daily at work, a helpful chart here, an addition to a procedure there.

For me the best reference material is the material you don't even notice. When I look up and see a flip chart, that I've used a hundred times with the portion I need highlighted, I forget that it's even there. A keyboard template that seems to be part of the keyboard is another example. Keeping the reference material easy to get to and easy to read and understand seems to be the key to having good reference material documentation.

Barker Ch3

2006-09-13T08:49:00.000-07:00

Barkers chapter 3 is titled Writing to guide – procedures, and is about creating guidelines for writing your procedures. I felt that this chapter was particularly important because at my work I end up writing documentation for every application that I own, which right now are only about four. Writing the documentation for the applications that I write is a continual process and if I don’t follow a set of guidelines through all my applications then each one just would become its own mess. I easiest part of writing documentation for the applications that I create is writing for the appropriate audience since the applications I write are services utilized within our framework my audience is going to be other programmers so I can write my documentation in a way where I could learn from it.

Ted's Intro

2006-09-06T12:52:00.000-07:00

A little slow figuring this out. I don't think I've ever blogged before. I'm returning to school to finish up a Speech Major and English Minor. I am a Systems Engineer at Medtronic in Shoreview MN. Technology has changed a lot since I went to school and what many of you take for granted is coming a little hard for me. I should be able to muddle through, I work in a technology field, but business technology and educational technology seem to have a few differences.

Campbell Chapter 3

2006-09-06T08:59:00.000-07:00

The third chapter in the Campbell text is titled "Isn't There a Law Somewhere?" This chapter deals entirely with the legal side of policy and procedure writing, and answers questions about what actions are illegal, why certain actions are illegal, who can be held responsible, and how it is possible to avoid litigation. Basically, this chapter is all about legal responsibility.

One of the key points of this chapter is the topic of ambiguity. Even though precise and accurate language is one of the most important aspects to anyone in the English department, and more specifically, anyone in the Technical Communication niche, it seems far too easy to make the mistake of being unclear to your audience. However, in the corporate world, ambiguity in policies and procedures can easily mean a lawsuit against you or your company. This is incredibly easy to understand, as you don't have to look much further than the newspaper to see suits being processed over seemingly mundane and minutial details.

Campbell Chapter 2

2006-09-04T19:43:00.000-07:00

This chapter covers the planning and development of a document. The four steps of development include: planning, analysis, research, and prewriting. Many people make the mistake of going right to step four and prewriting when creating a document, but Campbell says on page 27, "Even thought you may be under tremendous time pressure go through each step at least briefly." This is especially important when working in teams, because a lot of time can be saved by good planning sessions.

Each step of development is important for its own reason. Planning helps the writer to focus while analysis provides information about the audience. Research finds information about the topic and prewriting organizes everything.

Barker chapter 2

2006-09-04T09:49:00.000-07:00

Chapter two from Barker’s text really made me reflect on the various tutorials and help menus that I have used. Some of them were very helpful, while others left me more confused than before I had started. I once tried using a music program that created track lines and played them back. The program presented itself on the screen as a confusing jumble of buttons and sliders that anyone would be hard pressed to comprehend without some sort of tutorial. I clicked on the help icon, which lead to the tutorial. The tutorial appeared in the shape of a small side menu with different buttons that lead to different topics. Unfortunately, the tutorial didn’t present much help. It made brief explanations about various feature, but it never really covered the basics of how to manipulate a lot of the buttons. The program didn’t cost anything, so I felt no remorse deleting from my computer.

I encountered one good example of an embedded tutorial within a computer game. The game throws you into its world rather abruptly, but helps you get acquainted with how it works very quickly. A window pops up every time a new idea comes along, and gives you a brief description of what needs to be done. After a while, when all the main ideas have been covered, the help windows stop popping up. By that time the little popup windows have explained enough information to deal with anything the game throws at the player.

Barker Blog - Chapter 1

2006-08-31T20:31:00.000-07:00

Chapter 1 in the Barker book is titled “Understanding Task Orientation.” One of the most important things that this chapter talked about was identifying the user. When writing manuals and documents, you must know you the reader/user is going to be to make the document as efficient as it can be. Another thing that this chapter talked about was goals of the software user, which were learning a program and applying the program.

I’ve had some problems at work that could relate to this chapter. We got new computers at our desks with new programs on them to use. After installing the new computers they really didn’t explain to us how to use the new programs. We got big binders with instructions on how to use it, but didn’t have the time to go through and read it. This could have been an example of “information overload” as stated in the chapter. We couldn’t really learn or apply the programs. The words and phrases used were more for computer savvy people, and many of my co-workers are no such thing. I think this chapter is important in that people really need to know their audience when writing any sort of document.

Chris Stalboerger Intro

2006-08-30T13:32:00.000-07:00

My name is Chris Stalboerger Im a Computer and Information Science Major and Technical Communication minor. I currently plan on graduating this semester. I just finished up my internship this summer with Thrivent Financial for luterans as a programmer.

Campbell Blog - Chapter 1

2006-08-30T13:11:00.000-07:00

The title of chapter one from Nancy Campbell’s book is “What’s a Policy, What’s a Procedure.” I found this chapter interesting because the backbone of any organization is the policy and procedure. Without policies nobody in the organization will know the rules. The procedure will show more specifics on exactly how the organization goes about getting the work done.

After reading this chapter I could see where I could apply many of these rules such as ambiguity, unwritten rules, and level of detail to the Constitution and By-Laws of my fraternity. The Constitution is the policy, stating the rules and what we stand for. Our By-Laws are the procedures; i.e. how we handle everyday proceedings. I found the most important part of the chapter to be the “Overload Alert” from page seven. Campbell notes that there is “a danger in creating a policy or procedure for everything.” I totally agree on that and believe that some people in my fraternity jump the gun to get every last thing in writing. However, there needs to be a balance between written and unwritten rules. As long as the unwritten rules are being followed there is no reason to formally write everything down.

I hope this course can show me more ways to correctly word and interpret my fraternity’s documents to get more real world Technical Communication experience.

Heuer for Dummies

2006-08-30T12:48:00.000-07:00

My name is Ryan Lee Heuer. My life began in Redwood Falls and quickly switched scenes to Mankato. I am enrolled in the English department at MSU and am studying Technical Communications. Mathematics is my minor. I have been rocking out in all my English courses which include Technical Editing, Desktop Publishing, and Technical and Scientific Literature. During those classes I have learned how to utilize some desktop publishing programs like InDesign and FrameMaker, as well as Word. I took three years of Spanish in high school, but if you say anything to me in Spanish beyond hello, I probably won’t understand. I’m not exactly sure where I’ll be after college. After college I plan on becoming a pro wrestler or obtaining super powers and fighting crime. But most likely I will become a technical writer who makes enough to pay his bills without worrying too much about his budget.

Jordan's Introduction

2006-08-30T12:30:00.003-07:00

Hey everybody! My name is Jordan and I am a Management major and Technical Communication minor at Minnesota State University – Mankato. I grew up in Worthington, Minnesota which is a small town about ten miles from the Minnesota-Iowa border. I am starting my junior year at MSU – Mankato and have a total of two years left of my undergraduate classes. I am very involved on campus in Phi Delta Theta Fraternity. A lot of my technical communication experience has been in my fraternity and in my work experience. I am currently a student worker in the Office of Academic Affairs here on campus.

Johnsen Introduction

2006-08-30T12:30:00.002-07:00

I'm a 4th year Technical Communication major, with a Computer Science minor. This year will likely be my last year here at MSU, unless I end up needing another semester of classes or an extra summer to graduate.

The other classes I've taken in the Technical Communication are Technical Communication, Technical Editing, and Desktop Publishing. As far as my minor goes, I pretty much have completed every class required for a CS minor, except one or two.

My goal is to use my future Technical Communication degree to secure an entry-level job, then when I have enough experience, I'll either branch off and work independently or shoot for an editing job, as editing is my favorite area of TC thusfar.

Andrews Intro

2006-08-30T12:30:00.001-07:00

I'm Jessica Andrews and I am a senior. I am a Technical Communication major and Communication Disorder minor. I look foward to graduating in the spring but will continue my education. I currently am looking at graduate schools to get my Master's in Education.

Though I would love to teach, I would also like to work for a publishing company. The one aspect of technical communication jobs I have no interest in (or skill for that matter) is publishing. I prefer copy editing, but I realize that as a poor college student I should just take any job I am offered.

Ashley's Introduction

2006-08-30T12:30:00.000-07:00

My name is Ashley Gerdes. I'm originally from a very small town, Ormsby, in southern Minnesota. I now reside in North Mankato. My major is Sociology and my minor is Technical Writing. I would like to go into the Human Resources field, and I thought that the Sociology degree would help with working with people and things of that nature. I figured that the Technical Writing minor would help with writing any documents, such as memos, policies, procedures, etc. that may be involved with that profession.

I'm a senior this year, and hope to graduate in May. I have one more Technical Writing class to take during the spring, and I still have an internship to do, which I may have to do during the 2007 summer. I would like to stay in the Mankato area if possible after graduation.

A bit about Zach

2006-08-30T12:24:00.000-07:00

I am a Technical Communication major with a minor in Social Welfare. This is my 4th year at MSU, Mankato and my 2nd semester towards the Tech Comm major. In the future, I hope that I will be able to use this degree for a job that involves creating technical documentation for computer programs or proofreading/editing.

Welcome to the Engl 477 F2006 blog

2006-08-28T15:16:00.000-07:00

We are blogging Barker and Campbell's textbooks this fall semester. The idea is to connect your own technical communication experience, whether it is professional, academic, or personal, with Barker and Campbell. So in the chapter in Barker on Writing to Teach-Tutorials, you might make connections with the on-the-job training you received or delivered in a job you have held. I look forward to an interesting blog discussion.