Robert Pierce

Automatically connecting documentation to code with rose

One of the most common problems with program documentation is keeping it synchronized with the source code it purports to explain. One solution to this problem is to automate the documentation process using reverse engineering technology. Reverse engineering is an emerging branch of software engineering that focuses on recreating high-level information (such as program documentation) from low-level artifacts (such as source code). This paper describes an automated approach to maintaining the connection between documentation and code by leveraging the reverse engineering capabilities built-in to Rational Rose. The approach produces application programming interface documentation for component object model-based (COM) dynamic link libraries (DLLs), C++ source code, and Java archive files. The documentation is always accurate and up-to-date. A primary advantage of the approach is its reliance on an industry-standard tool, thereby addressing one of the main concerns with facilitating wide-spread tool adoption: commercial-level support of deployed products.

Using customer input to drive change in user assistance

If designing and developing optimal products, services, and information requires clarity and audience awareness, then developing ways to acquire customer input is a critical piece in the best development workflow solutions [43]. Seeking direct input from customers and learning how they use a product are the most effective methods for generating ideas for enhancements and innovations to the technical content that supports a product, as well as to the product itself [21]. Taking the steps to create opportunities for customer feedback enables direct customer input and establishes the proactive best practice of demonstrating to the customer that they are a top priority in the product development focus [34]. While there may not be a fixed agenda for an optimal customer meeting, there may, in fact, be a set of topics for discussion that comprise a set of best practices for gaining customer input for the user assistance [45]. Customer input helps provide requests for change and thus aids in managing change, raising the importance of a change and requirements management system [34, 52]. A change and requirements management system is even more critical in the context of application lifecycle management and globally distributed development [27, 49, 50, 55]. Managing relationships with customers leads to a two-way path for collaboration, both for helping customers solve their problems and for a company to enhance its products and overall success [26, 28].

Leveraging technology affinity: applying a common set of tools and practices to information development

The six best practices of software development can be applied to the development of each component of a finished product or project. Each organization within an enterprise can design and implement a process that encompasses these best practices. And there are software development tools that enable each best practice.This paper describes the six best practices, the tools that enable them, and demonstrates how they can be applied to information development, as well as other all components of software development.This paper also provides an example that illustrates how documentation groups or organizations can benefit by following these best practices to ensure success for information development projects.

Resources to support computer programming learning and computer science problem solving

In this paper we analyze the use and the preference of several types of resources either to improve knowledge of software programming and programming language or to solve specific problems by using those languages. Answers to these questions may be especially important either to teachers or to writers of technical communication. Collaborative tools may also be part of the solution to meet student information needs.

Globally distributed content creation: developing consumable content for international markets

This paper examines the globalization of content from the perspective of consumability. The authors describe how technical communicators can use a globally distributed approach to manage the translation of technical content. In so doing, the authors examine how technical communicators might use iterative development practices to improve the development of technical communication products (e.g., software manuals, online help, context-sensitive help, or dynamic help available on the Web) for international audiences of consumers.

Panel design of communication: new steps

SIGDOC comes from a technical writing tradition, where literature and rhetoric play an important role. Communication is now giving a broader focus, especially as influences come from graphical design, web design, digital sound or digital multimedia. In Lisbon, we expect to discuss this focus of SIGDOC. This is an important transition that is being done, without loosing its identity. In fact, from the revision process the heterogeneity of view point was identified. This is the result of including more participants from multimedia, computer science and graphical design. For the second time, SIGDOC will take place outside the American continent. For the first time it takes places in a non-English speaking country. It is the ideal place to discuss an important issue either for the technical documentation, either for software engineering or for design of communication communities: translation, internationalization, localization, and globalization. Bologna process is transforming and making an authentic revolution in the European university panorama. This may be faced either as a threat or as an opportunity. In this context, the discussion about a curriculum in design of communication is an important step that may be undertaken by the SIGDOC. It is a step that may contribute to its affirmation either in academia or in practitioner context.

What is design of communication

What is the Design of Communication? In this panel, four SIGDOC members from different areas come together to discuss the interdisciplinary area of DOC.

Working from home in a globally distributed environment

This experience report provides an overview of working in globally distributed teams and the role communication technologies and protocols play in the successes of such teams. It describes technical and social aspects for interacting in such teams.

SIGDOC: reviewing the history from a company perspective

SIGDOC is the Association for Computing Machinerys Special Interest Group (SIG) on the Design of Communication (DOC). Until 2003, SIGDOC focused on documentation for hardware and software. With the shift in focus from systems to computer documentation to the design of communication, SIGDOC has better positioned itself to emphasize the potentials, practices, and problems of multiple kinds of communication technologies, such as Web applications, user interfaces, and online and print documentation. SIGDOC focuses on the design of communication as it is taught, practiced, researched, and conceptualized in various fields, including technical communication, software engineering, information architecture, and usability, etc. The traditional SIGDOC members were likely to be teachers, researchers, and/or practitioners of computer documentation. Today, members of SIGDOC include information design professionals, educators, researchers, software engineers, Web designers, system developers, usability specialists, computer scientists, user interface designers, and information technology specialists. What is the next sustainable change on the Design of Communication?