Rob Pierce

Optimizing your documentation with the help of technical support

Maintaining technical support is costly. Better documentation means more successful customers AND lower costs of supporting a product.Most companies have two bodies of technical information that in many organizations remain entire to themselves. The information presented in the companys documentation deliverables and in their technical support data repository are not always consistent. There can be a real issue of redundancy and inaccuracy between these two areas of information.It may be common knowledge that working with Technical Support can improve your documentation deliverables, in theory. But in practice, there is frequently not a seamless integration of technical information, unless mandated by management for documentation groups and technical support groups to work together.This paper is a case study of this situation and presents some ideas on how to improve the probability of ensuring that one unified body of information is presented to customers. It is derived from experiences gained through working with a large body of technical content for a widely-used product, that includes application programming interface (API) reference information in the form of a Help system and a 900 page pdf file that ship with the product and access to a solutions database that is accessible from the Internet, given proper authentication.

Notes from the chair

On March 14th I attended the ACM SIG governing board meeting in Chicago where I presented slides to the other SIG chairs and ACM executive committee about the progress weʹve made over the past year as a small but vital community in ACM and we received a two year viability approval with positive encouragement about the steps weʹve taken to help ensure and promote the ongoing health, visibility, and growth of SIGDOC. This is a wonderful result and bodes well for our current stability and ongoing potential for an improved future.

Designing communication for a system of systems

Systems can be extremely complex, and contain many subsystems and components. The presentation of a system of systems adds layers of complexity both to the basic concepts of the system and all the details required for each area of the system that may be applicable to a type of user or role, function, or operation. It becomes more critical and yet more difficult to provide clear and comprehensive overviews and details of a system and its subsystems and components, as the complexity increases.

More thoughts on what is design of communication

Developing technical content and “Communication” elicits less debate or discussion than the Design aspects of communication. Design is a simple and elegant term that represents much potential or hidden complexity. And, good design requires a broader array of skills and perspectives from designers than the skills required for developing information. But what are some of the broad areas of skills and study for good design?

Modeling an information architecture

There are few resources for technical writers who wish to document Software Development Kits (SDKs), the resources that help software developers create new software and integrate existing software. This research will present the following results of online surveys and interviews:  Advice from practitioners on best practices.  Breakdowns of specific SDK-related tasks performed by practitioners.  Background knowledge required for each task.  Specific subject matter knowledge used for tasks. If you are interested in or contribute (as a writer, editor, project manager, or programmer) to this work, and would like to contribute to this project, please complete the following short survey: http://webq.catalyst.washington.edu/survey.cgi?user=bottoc&survey=2 This survey is part of a research project for a graduate student at the University of Washingtons Technical Communications Department. For questions or feedback, please contact bottoc@u.washington.edu. The goal is to determine best practices for writing programming documentation and to develop training for technical writers interested in this area.

An introduction to documentation testing

Interested in or Work on Developer Documentation or SDKs? There are few resources for technical writers who wish to document Software Development Kits (SDKs), the resources that help software developers create new software and integrate existing software. This research will present the following results of online surveys and interviews:  Advice from practitioners on best practices.  Breakdowns of specific SDK-related tasks performed by practitioners.  Background knowledge required for each task.  Specific subject matter knowledge used for tasks. If you are interested in or contribute (as a writer, editor, project manager, or programmer) to this work, and would like to contribute to this project, please complete the following short survey: The goal is to determine best practices for writing programming documentation and to develop training for technical writers interested in this area. When developing software or developing technical documentation, it is imperative to verify the accuracy and completeness of what you are planning to deliver. Testing is a fundamental best practice in software development. And, while testing your software is imperative, the best of quality assurance intentions will fail if the following variables are not accounted for in advance of any actual testing effort: A lack of time, resources, or formal test cases planned to be followed can lead to application instability, late system delivery, or a higher number of defects delivered to end users and customers. For the information developer, a lack of formal testing may result in similar errors and issues with a Help system or context sensitive Help within an application.

Parallel design and development for documentation projects

Interested in or Work on Developer Documentation or SDKs? There are few resources for technical writers who wish to document Software Development Kits (SDKs), the resources that help software developers create new software and integrate existing software. This research will present the following results of online surveys and interviews:  Advice from practitioners on best practices.  Breakdowns of specific SDK-related tasks performed by practitioners.  Background knowledge required for each task.  Specific subject matter knowledge used for tasks. If you are interested in or contribute (as a writer, editor, project manager, or programmer) to this work, and would like to contribute to this project, please complete the following short survey: The goal is to determine best practices for writing programming documentation and to develop training for technical writers interested in this area. It is common for a company or organization to be working on different versions of a particular deliverable concurrently. This is commonly known as parallel development. If two product development cycles and release dates are planned in the future, one in six months and one in eighteen months, then a likely scenario of developing two versions of a product at the same time may occur. In software development, there are not only feature releases but service releases and hotfixes or patches. How changes are tracked and included between one version and the next, can become a complex management task. And the level of granularity on managing changes between one version and another applies not only at the product level but for each particular source file in a product. While some files are required by different components in a product to correctly function such as a DLL or EXE, even html, text or other document files need to be tracked and managed between product releases and differing versions. The term parallel development is a bit generic in that it typically encompasses all aspects of product development including design, development or implementation, debugging, testing, and documentation. To be more specific, since the development cycle includes design, development or implementation, testing, debugging, and documentation, there will be iterative development and stages or cycles of types of work at different

Documentation tooling and conversion issues

 Specific subject matter knowledge used for tasks. If you are interested in or contribute (as a writer, editor, project manager, or programmer) to this work, and would like to contribute to this project, please complete the following short survey: http://webq.catalyst.washington.edu/survey.cgi?user=bottoc&survey=2 This survey is part of a research project for a graduate student at the University of Washingtons Technical Communications Department. For questions or feedback, please contact bottoc@u.washington.edu. The goal is to determine best practices for writing programming documentation and to develop training for technical writers interested in this area.

What is round-trip engineering to an information developer?

outsource some of their IT functions, a variation on telecommuting as the work is done remotely. Some of that work has gone overseas, where developers get paid less than 20 percent what U.S. counterparts receive. But Software Outsourcing Research executive director Marty McCaffrey says offshore outsourcing has many hidden costs, including the extra effort involved in coordinating a project remotely. Telecommuting, meanwhile, has also been touted to save money, though those arguments may not hold up while corporate revenues remain depressed; lack of office space, for example, is no longer an issue as it was during the tech boom because of years of downsizing. Still, the International Telework Association and Council found in September that the number of U.S. employees who work from home at least one day per month has increased 40 percent in the last three years, while about 42 percent of those telecommuters work from home one day per week. IT staff are the most likely to telecommute because they can deal with technical issues better than employees who are not as tech-savvy. Robert Half Technologys Jeff Markham says executives are another segment being offered telecommute options. As the economy improves, telecommuting may prove to be a mixed bag for IT workers because it can make outsourcing a more likely option, while also signaling an employer wants to retain that worker by offering a telecommuting option. View Full Article: http://www.newsfactor.com/perl/story/22822.html

Seamless integrations with engineering: or, keeping documentation issues transparent

This brings me to a real issue for software technical communicators, how to walk the fine line between creating technical documentation content and how that content is actually created. This is the line between the engineering world and the documentation world. Getting your information is one thing, using documentation tools and following documentation standards and best practices is another thing. And for sure, these are two very different worlds.