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.
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.
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.
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.
Shorter topics do add more little targets in the field. So the user has a higher chance of hitting one of the targets, but it’s unlikely that any of the targets will provide the exact answer the user is looking for.
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.
Technical communicators around the world are turning to the World Wide Web us their primary delivery agent for on-line documentation. The transition from older forms of on-line documentation to HTML-based documents pre - sents new challenges in every phase of the documentation process: document creation, layout, access, and especially hypermedia capability The constant development of new web tools presents an even greater challenge for an organization seeking to stay abreast of technology with an ever decreasing budget. This panel will outline the basic steps in migrating to the web while focusing on one organization’s solution to meeting the challenges of restructuring its on-line documentation for web migration.
I have been playing around with Crucible, Atlassian’s peer code review tool. The latest version of Crucible allows you to review Confluence wiki pages. This is a new feature, so I decided to try it out. Also, I was wondering why you might want to use an independent tool to review a wiki page, when you could instead just add comments to the page or update the page directly.
Good organization, complete information, and clear writing are, of course, key to the success of any design document, but there are some other, less-obvious techniques you can use to make your documents more readable and understandable. Here are a few of them.
In Publishing 2.0, Tim O'Reilly says Web 2.0 is 'any network effect that makes a system better the more people use it.' Web 2.0 isn’t just user-generated content; it’s harnessing the collective intelligence of your users to make your system better.
If Web-based user documentation can improve a company’s Web site ranking, then it makes sense for technical writers to take advantage of this fact. So if you’re writing Web-based user documentation, how willing are you to change your writing style for Search Engine Optimisation (SEO) considerations?
When it comes to an about page, think outside the box. Try to think of something new and creative that’s different form the rest of your site. Of course display images of you / your staff, and descriptions of each, but try to lay it out in a very fun way, whistle keeping it clean and readable.
As help systems continue to evolve, whatever name they are called, we will increasingly have to face responsibility for their content, and bring their expertise to what we write. The new systems provide us with all the required tools that tell us the problems with their content. It is up to us to leverage that information to provide better content, and act as ambassadors for products that we write. If writers can go a step ahead, and use their help information to sell products, and reduce the burden on customer support, we would have truly arrived.
I’m studying different help sites and applying web analytics. I wanted to write up some of the processes, potential wins, and possible shortcomings of web analytics for technical communication.
Is the behavior of someone using a help system the same as the behavior of someone using the web. Does help stand in a unique genre of material, one that plays by different rules, even when it’s on the web? Do users recognize official help material and dive more deeply into it, browsing and searching rather than immediately discarding it? Or do users act with the same behavior as they operate on the general web?