One page or separate pages? When faced with that decision, ask yourself these questions: How much do people want in one visit? How connected is the information? Am I overloading my site visitors? How long is the web page? What’s the download time? Will people want to print? How much will they want to print?
Rather than spend hours coming up with a complex numbering scheme, this might be an excuse to implement something far more straightforward discovered by an extensive readability study at IBM, of which I was a part. My work involved sitting behind a one-way mirror with a stopwatch, watching people take tests that involved, among other things, "how fast can you find Figure 3-4?" We had cameras mounted over the participant's shoulders and could watch them thumb through the documents, and we also monitored eye movements. Then we followed up with a short interview where we got feedback.
A Content Curator is someone who continually finds, groups, organizes and shares the best and most relevant content on a specific issue online. I think that professional writers and technical writers should consider a move towards this role. We already search for and find the best content, sift through loads of content, discard poor content, and publish the most worthy content whenever a software release goes out. This description also sounds like something a content strategist would do as part of their analysis of the content.
It's hard to look at a page of text and try to decide where to divide things to create individual topics. That "bottom up" approach is kind of pointless, in fact. There are better ways.
After the novel, and subsequently cinema privileged narrative as the key form of cultural expression of the modern age, the computer age introduces its correlate - database. Many new media objects do not tell stories; they don't have beginning or end; in fact, they don't have any development, thematically, formally or otherwise which would organize their elements into a sequence. Instead, they are collections of individual items, where every item has the same significance as any other.
For a long time I have been an advocate of quality content on web sites. And now I am conducting an experiment that pitches quality content against immediate gratification.
The way I learned to write documentation was that you started work on a new project by spending a decent amount of time getting to know your subject matter. I don't mean getting to know the software, I mean getting an understanding of the environment in which the software will be used and the reason for its existence - that is: what's the real value of the software to its users and what do they want to achieve by using it?
The usefulness of concept mapping as a job performance aid for writers of technical documents was examined. Thirty-four writers were randomly assigned to one of two groups. The experimental group received 2 hours of training in the use of concept mapping. Both groups revised the same chapter from a computer manual, and an experienced technical editor blindly evaluated each revision. In part two of the study, revised texts were given to two groups of users. One group received a concept-mapped revision, while the other group received a text revised by a writer who had used conventional revision techniques. Readers' comprehension was tested and compared. Revision time was not significantly different between groups, and the editor's ratings of quality were not different. However, readers' comprehension was significantly higher with the concept-mapped versions. These results suggest that concept mapping is a useful revision tool for writers.
Work with structured abstracts--which contain sub-headings in a standard order--has suggested that such abstracts contain more information, are of a higher quality, and are easier to search and to read than are traditional abstracts. The aim of this article is to suggest that this work with structured abstracts can be extended to cover scientific articles as a whole. The article outlines a set of sub-headings--drawn from research on academic writing--that can be used to make the presentation of scientific papers easier to read and to write. Twenty published research papers are then analyzed in terms of these sub-headings. The analysis, with some reservations, supports the viability of this approach.
Perhaps our headings should focus a bit more on user benefits? For example, "Overview of batch printing - Save time and improve document organization" is a bit more engaging, especially if your customer is struggling with those issues.
Hypertext is a novel approach to computer-based information management based on associative indexing. The concept in general and the characteristics of typical systems are briefly reviewed. Strategies for applying hypertext techniques to the process of writing a technical document are examined. The way in which hypertext documents are used is discussed, focusing on a commonly encountered problem -- user disorientation within the document. Hypertext-based technical documents are compared and contrasted against their paper-based antecedents.
Information Architecture (IA) as a discipline practiced by professionals in the information processing and development industry has many definitions and levels of understanding.
This article argues that, despite the seemingly mechanical context and nature of the underlying process of writing instructions, written instructions ARE works of art, because creative thinking and problem solving are essential to achieve the following goals of instructional writing.
In the tradition of work by Shaughnessy (1977) and Bartholomae (1980) applying concepts from second language acquisition research to developing writing, we explore the commonalities of L1 and L2 writers on the specific level of linguistic choices needed to order information within and across sentence boundaries. We propose that many of the kinds of constructions in L1 and L2 writing most difficult to categorize, labeled as errors, are in structures that are, from the writers’ perspective, principled attempts to meet their obligation of managing information. We examine 90 essays written by college students, 60 by native speakers, and 30 by nonnative speakers, and identify 360 non-target-like structures that are attempts to manage information. There are similarities in number and type of these constructions used by L1 and L2 developing writers.
Book published by O'Reilly Media have a good flow to the information and they're well structured. One of the best features of many of those books is the introductory material. It can be a good guide, and help readers zero in on what they want to learn.
With my ongoing series on organizing content, I left off at the question of whether blog platforms would outperform help authoring tools as a way to organize content for web environments. I had a lot of thoughts about that topic, and actually created a blog theme for a documentation project as a test, but recently I received a new project on my plate, and my attention has shifted to another angle on this same series: organizing the content within the topic itself.
Language experts should play a more active role in shaping the interface because the interface is text. As such, writers do a disservice to project teams if they don’t play a role to help clarify and sharpen the interface language.
Moving help inside the interface has many advantages, and there are plenty of best practices for style and format. But the biggest shift in perspective, which I argued in my last post, is to stop differentiating between the interface and the help content. The interface is mostly text. It is an orchestra of words on a page that users rely on to navigate and understand the application’s content.
Owens explains how technical writers can bolster their credentials as technically knowledgeable employees. He provides brief introductions to technologies that technical writers are most likely to encounter on the job: programming languages, databases, and Web server technologies.
The ability to abstract information is a basic competency in today's knowledge society, characterized by the mass diffusion of information and the need to manage and access it effectively. Yet abstracting is not an easy task, and requires a specific learning process. This paper examines the process of abstracting information from the perspective of competencies and skills-based learning of students of information and documentation. The competencies and skills necessary in this process, which are drawn from European sources on library science and documentation, are identified by analysing in detail the various stages and processes involved in writing an abstract. The general skills required for the whole process, as well as the specific skills for each stage, are determined. Guidelines and recommendations are put forward to facilitate the learning of these skills in the context of abstracting.
This article looks at the impact of the introduction of semantic markup and structured authoring on the world of technical writers, editors, Help authors and content developers. This article is not specifically about the Semantic Web movement itself, but about the implementation of semantic concepts in the documentation field.