Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Good user documentation means fewer client support calls and lower support costs at GE Information Services in Rockville, Maryland.
Beyond the obvious impact on the Social Web, Google Wave is also going to change aspects of every business that currently relies on communication and collaboration tools of any sort, including the ubiquitous but lowly email.
Traditional models of usability assume that usability is a quality that can be designed into a particular artifact. Yet constructivist theory implies that usability cannot be located in a single artifact; rather, it must be conceived as a quality of the entire activity in which the artifact is used. This article describes a distributed approach to usability, based on activity theory and genre theory. It then illustrates the approach with a four-decade examination of a traffic accident location and analysis system (ALAS). Using the theoretical framework of genre ecologies, the article demonstrates how usability is distributed across the many official and unofficial (ad hoc) genres employed by ALAS users.
We often hear how the Web can be used to deliver technical documentation. But have you ever thought about the Web as technical documentation? When dozens, or perhaps hundreds, of people, all using the same product, start posting tips and solutions to problems on different Web sites, the entire Internet becomes a kind of crude users’ manual.
Listen up open source developers, if you want your project to succeed you’re going to have to do more than write great code; you’re going to have to document it, teach new users how it works and provide real-world examples of what you can do with it. That’s the message from Jacob Kaplan-Moss, one of the creators of Django, a very successful open source, Python-based web framework. At least some Django’s success can be attributed to its thorough documentation which is not just reference materials, but also includes tutorials, topical guides and even snippets of design philosophy.
A Guide to the Project Management Body of Knowledge (PMBOK® Guide)–2000 Edition is the main sourcebook in the project management field. Whilst it covers Project Communications Management, it doesn't extend to user documentation. This article seeks to provide guidance for project managers as to how the user documentation process fits in with the overall project planning. It examines: the traditional way documentation is approached and how it impinges on project planning the effects of making changes to this traditional approach.
Sample code often provides the quickest, clearest way to learn how an SDK works. If you have software engineering experience, then you should already know many principles for writing good code. However, what you may not realize is that some of the good practices that you learned for writing good production code do not apply to writing good sample code. Some techniques, such as comments and clear variable names, apply to both production code and sample code. However, there are good reasons to use hard-coded values in sample code, which should be avoided in production code, and there are good reasons to avoid object-oriented designs when writing sample code.
We have a number of projects running at the moment that involve us improving organisations’ policy and procedures documents. It may not seem likely, but these projects are enormous fun.
A causal-analysis session is a problem-solving method that brings groups of people together to jointly solve common problems and make process changes. This method ensures that everyone who will be affected by a process change has the opportunity to provide input and agree to the solution. In large departments, reaching group consensus is a challenge. This paper presents our department's implementation of the causal-analysis method.
Miller, a technical editor at Microsoft interested in multimedia documentation, talks about why multimedia documentation is a growing trend and how writers can get started. He discusses Microsoft's Channel 9 and the human element with instructional screen demos.
If you watch screencasts, you probably have seen some that are just worthless. How long did you stay to watch? Not long, I am sure. Why am I being so critical? Because it is true.
Before you release a product, have some people use it. From these "test users" get solutions to problems, tips and knowledge that would help your real-life Users. Put that information in your User Documentation, and on your product support website.
HAT-Matrix.com is a new representation of an old standard--the Help Authoring Tool (HAT) Comparison Matrix that was available from helpstuff.com for five years (2001-2006). But instead of a static list, this site uses a searchable database. And instead of someone choosing the tools that are included, vendors choose whether to include their tools.
Too often technical writers fall into the 'tell them everything and tell them all at once' pit. Guided by a well-meaning desire to 'educate' users, what these writers typically do is overwhelm them. Finding the information you need when you need it is a key to success in every business function of every company. Therefore, technical communicators who are able to provide their customers with quick and useful knowledge bring an incredible added value to a beleaguered work force constantly expected to do more and to do it faster.
Normally I like to write positive stuff and I really love Uxmatters.. it’s a great site. BUT, the recent article PDF Manuals: The Wrong Paradigm for an Online Experience from my perspective is pretty much everything that’s wrong with Help today.
As Help Authors, we often treat online help as a 'thing,' not an activity. We’ve favored the noun over the verb! This preference is natural for writers, who enjoy producing books. If we hope to survive on a dynamic development team, we must train ourselves away from writing books, toward helping people. This shift means examining the bigger picture and adopting different ways of working.
Two questions any writer must deal with are: 'What do I write about?' and 'How much do I say about it?' Essentially, these questions deal with the scope and the depth of a document. Technical communicators have a tendency to want to document a topic as completely as possible, and we carry this instinct with us when we architect and write Help files. In this column, I challenge that prevalent instinct and offer an alternative way of thinking about the scope and depth requirements of Help systems. The benefits of this approach are, I hope, better Help for users and, for our clients and employers, a more efficient use of technical communicators' time. First, I'll discuss three principles that underpin my perspective, then I'll give some practical advice about writing Help that people will actually use.
An increasingly popular component of modern graphical human-computer interfaces are graphical command buttons. Studies have shown that graphical command buttons can enhance user productivity. However, two factors, the time required to acquire a working knowledge of the graphical command set and the need for frequent use to maintain the knowledge limit the effectiveness of graphical command buttons as a user interface strategy. This study attempts to quantify the effects of four types of help (balloon style, a mouse documentation line at the bottom of the screen, a help browser, and hardcopy documentation) on the ability of novice users to acquire a working knowledge of a graphical command set. The study did not find any significant difference (based on the anova and manova tests) between the four treatments.
Tight deadlines and limited resources often force wiiters to cut corners and release less than optimal help system designs. After considerable trial and error, I te come up with a checklist that can help you evaluate and improve your help system for the next release. Each question represents an important usability issue.
If you work on a new-concept website—that is, a website that doesn’t follow an established format like an ecommerce site or a blog—producing user documentation might be the last task on your mind. Yet for sites that present processes unfamiliar to users, quality documentation is crucial.