This article identifies and explains format rules, style rules, and lexicographic conventions that have been shown to improve clarity and precision in a technical glossary. Rationale for the rules of language, presentation, and style are examined. The need to allow flexibility in following the rules is discussed in terms of strengthening the technical merit and vitality of the glossary. This article also describes the computer-display techniques and file-management system used in committee to develop U.S. Federal Standard 1037C, Glossary of telecommunication terms, and to display the results both in the meeting room and on the Internet between meetings.
The purpose of this document is to provide information and resources for those interested in learning more about accessibility issues and current and next-generation information systems. The current focus of this document is on the National Information Infrastructure (NII), sometimes known as the 'information superhighway.' This document contains both information presented at a very introductory level and information which is more technical in nature. Wherever possible, all of the technical discussions are broken out and presented separately, so that readers may course through the material at a level which is comfortable to them, and which meets their information needs. This is a living document which will be continually revised and added to as more information is collected and as the efforts in the area of research, development, and public policy continue to evolve. The most recent form of this document can be found on the Internet via our ftp, gopher, or WWW servers. All of these are located at: trace.wisc.edu The document can be viewed on-line or downloaded in one of several forms to facilitate accessibility.
I manage a group of editors at a software company. This topic describes how we strive to achieve consistency in editing software documentation among a group of editors both within a department and across divisions in a large company. We have a staff of 14 editors that serve five large writing departments. Our editors are excellent grammarians before they come to SAS, but they also get considerable training and mentoring in SAS specific guidelines when they join our staff. I acknowledge that it’s impossible to achieve 100% consistency across all editors, but consistency is worth striving for for several reasons.
Words go so well with video. They can give an emotional punch to a scene or simply announce what is going to happen next. I love using romantic quotes, Bible passages, and other forms of text in my work. The best part is that you can be just as creative with how those words are presented as you are in picking out the text in the first place.
It is important to alphabetize your index in a consistent manner. Otherwise, your readers may become confused or miss an important entry. There are two basic ways to alphabetize, or sort, an index: word by word; letter by letter.
'It's all in the manual.' How many times have you heard that - or said it in frustration? After all, when you are the person who wrote the manual, you know that all the answers are there. But time and again readers can't find what they need to know, or don't understand the material. Before you blame the reader, look again at how you've presented the material.
Adding alternative text for images is the first principle of web accessibility. It is also one of the most difficult to properly implement. The web is replete with images that have missing, incorrect, or poor alternative text. Like many things in web accessibility, determining appropriate, equivalent, alternative text is often a matter of personal interpretation. Through the use of examples, this article will present our experienced interpretation of appropriate use of alternative text.
Technical writers are often responsible for creating and maintaining multiple documents. In organizations where a formal editorial review is integral to the documentation process, technical writers who own multiple documents might need to address a huge volume of editorial input, often received late in the documentation cycle. What do all of those editorial comments, when taken as a whole, really mean in terms of the overall quality of the document? Lots of red ink might mean either that the document is in bad shape or that the editor loves to explain every comment, however minor, in great detail. On the other hand, a short comment buried on page 63 might turn out to be the single most important editorial value-add for the entire document!
Imagine you are standing on a bridge casting a net. Above the bridge is your conscious mind, where thoughts come and go like travelers visiting a fair. Below the bridge is your subconscious—the ever-flowing stream of random thoughts, with countless ideas darting through the water like schools of brightly-colored fish. As is often the case where bridges and streams are concerned, a cold and menacing troll lurks nearby. This troll is your “Inner Critic.” The troll, aggressive and mean-spirited, doesn’t give a lick about your Grand Ideas. The troll has but one purpose: to prevent the ideas which playfully zoom about your subconscious from being gathered into the net of your consciousness and made manifest in the world. The resourceful and clever troll employs many tools to complete its task, ranging from the subtle (distractions and boredom), to the complexities of perfectionism, to diminished confidence and a paralyzing fear of failure. When the troll is in its élan (which is far more often than we’d like), its efforts decrease your ideation and productivity, dampening your awesomeness.
This article discusses some important issues in implementing a software documentation review process. If you are part of a small development organization and have few reviewer resources available, you may have to improvise techniques for providing the services and procedures suggested here.
A physicist-turned-editor shows you the basics required for copyediting physics papers (physical quantities, symbols, units, scientific notation, the structure of mathematical expressions, the nature of graphs), and points the way to learning enough 'editorial physics' to begin substantive editing.
But editing must surely take longer than reading. Maybe it takes, say, five times longer. That would mean editing about 12 pages per hour. Sounds good. Just read the page five times, and out pop the edits. Actually, that heuristic may hold true for a simple edit, but substantive editing takes more time - 15 to 60 minutes per page, some experts say. So, how long can editing take?
Marking up paper is still the most common way to review documents, but online review is critical if you work as part of a distributed team. There are advantages to online review even if you sit only a cubicle away from your reviewer. Here are few tips for making your online reviews go smoothly.
Editing is often narrowly defined as making corrections after a document is written. This approach typically relegates the editor to a low-status role within the organisation.
Style guides can improve the quality and presentation of documentation. They establish a layer of professionalism that may not have been there before. They also reduce arguments and ‘loose cannons’ within the department, as the style guide becomes the acknowledged reference. There are at least four points to consider when selecting a style guide.
After more than a decade of working in the corporate environment, I have finally accepted that readers need to be enticed by more than the promise of a good read: They need proof. They want a visual two-second test-drive before they decide whether or not to spend precious minutes on a particular page. This is not to say that corporate readers are not discerning or that sloppy copy reads any better when dressed up with elaborate design. The truth is that in any corporate publication, a great article won't be read if the layout is poor. Similarly, a stunning design falls flat if the content doesn't live up to it.
How do comments on student writing from peers compare to those from subject-matter experts? This study examined the types of comments that reviewers produce as well as their perceived helpfulness. Comments on classmates’ papers were collected from two undergraduate and one graduate-level psychology course. The undergraduate papers in one of the courses were also commented on by an independent psychology instructor experienced in providing feedback to students on similar writing tasks. The comments produced by students at both levels were shorter than the instructor’s. The instructor’s comments were predominantly directive and rarely summative. The undergraduate peers’ comments were more mixed in type; directive and praise comments were the most frequent. Consistently, undergraduate peers found directive and praise comments helpful. The helpfulness of the directive comments was also endorsed by a writing expert.
Creating and maintaining a high quality work environment that attracts and retains talented editors requires a commitment to excellence at all levels of a company or organization. A company dedicated to a nurturing work environment for its employees provides systematic training opportunities for professional growth. This paper describes how a company can meat its ongoing training needs for editors by offering formal and informal training programs and fostering learning at the group, department, division, and company levels.
This handout defines and shows examples of grammar, usage, and style errors commonly seen in undergraduate writing in the sciences. During class, students might be asked to revise each example.