Yesterday we launched a new version of our developer community website. It doesn’t have many ‘community’ features as yet but that’s all to come. One thing it does now have is an HTML version of all of our product documentation, in an easily searchable format. This new format of the product documentation is largely to move us away from PDF only documentation. At present we still have a set of PDFs but they aren’t particularly usable.
In this podcast, Nicky Bleiel says we should talk to as many users as we can — conducting on-site visits, sending surveys, gathering information from Marketing, Support, and other departments — so we can have a better understanding of our users’ needs and the formats and mediums that will work best for them. After completing this audience and needs analysis, we can then go out and create the deliverables that will best serve our users.
This is a story of how one internal project at Sun Microsystems migrated printed user and reference documentation to an internal Web site. The principle architect of this site discusses how she applied object-oriented design concepts to the Web architecture to accommodate many learning styles simultaneously. As important as the successes of this project are its failures, which offer some insight into when and how to use the World Wide Web as a communication vehicle in your overall communication strategy.
This article is based on my presentation at the Institute of Scientific and Technical Communicators' annual conference in October, 2006. Every now and then, there is a change in the value of what technical authors deliver. These are moments when organisations pay attention to technical documentation. This is because they recognise that these changes mean they can create something that will be of real value to the business and to their customers. In recent years, there have been three "waves of interestingness". The first wave was the introduction of Windows Help (WinHelp). The second major wave was the introduction of the Internet and intranets. This was a time when organisations looked at how they could transfer large amounts of information from paper to online. They were faced with issues such as how users could access and understand all this information easily - issues that technical communicators deal with on a day-to-day basis. I believe we're just about to approach the new wave, which we have called "Tech Writing 2.0".
This article is based on my presentation at the Institute of Scientific and Technical Communicators' annual conference, in October 2006, on new trends in technical authoring. It covers the application of Web 2.0 technologies to technical documentation.
With all the talk about Web 2.0 and the attendant technologies, are readers actually being better served by documentation now than they were in the past?
Although tools like eHelp's® RoboHELP® Classic can speed up and streamline the process of creating help topics, there are still many repetitive tasks needed to build a WinHelp system that supports a large, integrated application. This article summarizes one of the techniques that Fredrickson Communications used to automate the process of developing online help topics. Once the underlying structure and macros were in place, we were able to generate hundreds of help topics at the rate 15-20 per minute.
Screen recordings are a valuable tool for enhancing training, tutorials, manuals and websites. Companies use this technique to produce streaming and downloadable content. The recording tools are readily available and affordable. In this article, we explore some techniques, tips and tricks for recording sound, mouse movement and happenings from your screen to an AVI file. We will talk in both general terms and use specific examples. The examples pertain to HyperCam, a downloadable screen recording application from Hyperionics Technology. Like most screen recording applications, HyperCam captures the action from your Windows screen -- including cursor movements and sound -- and saves it to an AVI movie file.
Software user guides have traditionally provided assistance when the user requested help. Context-sensitivity enabled help systems to predict the most appropriate topic to present. For Windows applications, the move from Microsoft WinHelp to the new Microsoft HTML Help format allows user instructions to be presented in the same window as the application. This offers technical authors some extraordinary opportunities to provide intelligent, predictive, interactive help without the user having to request it. In this paper, we will explore one of the first such interactive help systems (for the Archivist e-mail archiving software), and see where the technology is moving.
Surveys and focus groups show that most software buyers use ReadMe files. Users primarily look to ReadMe files for information on software bugs. They identify the following ways that software manufacturers can improve their ReadMe files: 1) keep them short, 2) include a table of contents, 3) use hypertext, and 4) eliminate the need for ReadMe files. Along with these four improvements, this article discusses other ways to create quality ReadMe files that meet concrete user needs.
Web knowledge bases offer an excellent platform for delivering technical documentation and customer support information. They also represent an area of great opportunity for technical communicators to expand their skills, satisfy their customers, and create value for their employers or clients. This session explores the components of a web knowledge base and the tasks involved in planning and building one.
Braun Corporation's home-grown documentation processes served the organization well for its first 50 years as it grew from a local to a nationally-competitive producer of mobility and accessibility products. Now poised to become a global leader in its field, this corporation found its efforts hampered by ineffective and outdated documentation practices, which were hurting the company's competitive advantage. This article describes Braun Corporation's curious mixture of global reach and local isolation. By bringing in a technical communicator with expertise in user-centered design, Braun has begun reforming its formerly exhaustive documentation and communication practices. While technical communicators have incorporated a variety of strategies to develop user-centered and task-based documentation, less attention has been placed on changing the cultures of these organizations. The case presented here represents a shift from establishing documentation procedures to critically assessing and reforming existing procedures for the global workplace, describing the shift from ineffective and exhaustive processes to effective processes with defined goals and measurable outcomes. The article concludes with an inventory for determining whether other organizations are over-documenting processes and products, and offers suggestions for creating better documentation procedures.
Often conflicting pressures to produce communications that better fit customer demands as well as stay within tightening constraints on budgets and schedules are leading many technical communications organizations to a topic-based approach to authoring. In fact, 58% of participants in Aberdeen Group's October 2008 DITA and the Technical Communicator’s Transformation study report that they currently follow author content in a topic-based manner, with a vast majority of those remaining planning to implement one in the future. A topic-based approach promotes greater content reuse and is seeing a considerable impact on the authoring efficiency of technical communications projects today. The benefits of topic-based authoring can be compelling, with findings from the The Technical Communicator’s Transformation study indicating that when pursued the right way, topic-based authoring can have a broad range of benefits, enabling an organization to meet authoring and localization cost targets as well as documentation quality expectations, among others. However, as the adoption of this approach spreads, the advantages seen by today's leading organizations will flatten out. This Sector Insight provides a guide for current adoption of topic-based authoring and those still considering it; outlining the changes that are expected to take place in as topic-based authoring goes mainstream.
Apple's first user manual was largely the creation of Ronald Wayne, Apple's third founder, recruited from Atari by Steve Jobs for a 10 percent stake in the new company. Wayne not only wrote the entire 10-page booklet, he also drew the intricate cover logo depicting Isaac Newton beneath an apple tree.
When purchasing complex software products, users frequently receive large quantities of information; however, to use the product efficiently, they need a visually obvious starting point that helps them locate the specific information they need. With maintained With the quantity and diversity of information, customers need to be able to find the information they need without flipping through endless pages. In order to give the users a starting point in all of the printed and ASCII file information. we created a document entitled the Guide to products, users can use the features available with a new release most efficiently if they have an overview of the major changes to the product and to the information about the product. By using visual devices and creating an overview document. for each release, technical communicators can decrease their costs and increase users' productivity.
A comparative evaluation of two user guides,--the document traditionally used by a company and a model document designed on the basis of research results and recommendations,--was carried out using a number of complementary approaches focusing on the user. The quality and suitability of these documents for the target audience were assessed in terms of content, structure, presence of certain organizational devices (such as headings) and pictures included. The results revealed that the model document was more attractive, more efficient, and better adapted to users' needs, thanks to its modular organization (being structured according to "functions"), a large number of pictures, the presence of headings, and rationalization of the vocabulary used.
The web allows us to easily provide updated documentation to our users, but why stop there? There is more to making users successful quickly than just providing documentation. By creating a complete 'Answer Station' that is accessible from the application or product, we can not only direct users to that updated documentation, but we can also provide information about technical support, consulting, training, sales, etc. This article discusses writing a proposal for an Answer Station, determining content, working with other departments to gather information, designing the site, making that design work with an existing corporate website, dealing with tool issues, and finally, going live.
This podcast talks about the convergence of web 2.0 with help documentation. It mentions examples of Web 2.0 sites, such as Flickr, Payscale, and Digg, and what help files need to incorporate these same Web 2.0 features.
You’re told that you need to move your content to XML. You have loads and loads of unstructured content. It’s in FrameMaker, Word, other desktop publish applications, or even more fun: it’s on paper.