Levels of Maturity in API Documentation  

This paper proposes a set of API documentation maturity levels that can be used to define a writer or writing team’s ability to document technical materials and to set goals for moving between levels towards more independence from developers. It examines development and documentation team process maturity, as well as several types of API documentation, and their impact on writers new to producing developer documentation. The paper also discusses some of the common difficulties associated with developer-level documentation.

Kozlowski, Paula and Benjamin Dollar. STC Proceedings (2004). Articles>Documentation>Programming

Lightweight Literate Programming: A Documentation Practice    

Lightweight literate programming (LLP) combines software documentation and coding in a way that can scaffold collaborations between technical communicators and programmers. We review the genesis and history of LLP, including its relationship to established single-sourcing methods. We then detail its use by programmers and discuss two models for writer/programmer collaboration using LLP. We finish by suggesting a few studies of working relationships between writers and programmers that LLP could facilitate.

Stavely, Allan, Lynda Walsh and John Shipman. Technical Communication Online (2008). Articles>Documentation>Programming>Methods

Looking At GUI Libraries: Spotlight On Infragistics

As a Graphical User Interface (GUI) programmer, I have many interface development tools to choose from. Over the years, my development environment changes to accommodate my needs. This often includes learning new languages and the tools that go with them.

Flowers, Natalie. Carolina Communique (2008). Articles>User Interface>Programming>Software

Make the Best Use of Asynchronous Callbacks

It takes some finesse to make the best use of asynchronous callbacks for Ajax data sources in JavaScript applications. This tip discusses why you should use asynchronous callbacks for Ajax data sources and gives examples of coordinating the readiness of mutually dependent application data sources that may become ready at undefined times with asynchronous calls.

Mertz, David. IBM (2007). Articles>Web Design>Programming>Ajax

Manuals in Extreme Programming

Here's a bit of a rant I wrote some time back, talking about how to write the manuals for an XP project by using writers as part of the team. It's a serious proposal, written with tongue a bit in cheek.

Jeffries, Ron. XProgramming.com (2001). Articles>Documentation>Programming

Multimedia Scripting: Starting Off Right  

Bunn discusses the art of preparing scripts for different media.

Bunn, Bill E. Intercom (2000). Design>Multimedia>Programming

The New Breed of Version Control Systems

CVS, part of the glue that holds open source development together, is showing its age. Many competitors have emerged recently, fixing misfeatures and adding new ideas. Shlomi Fish explores several current open source version control systems that may be better than CVS for your needs.

Fish, Shlomi. O'Reilly and Associates (2004). Articles>Content Management>Programming>Databases

Oh, Oh! The Job Ad Says OO  

More and more job notices request some knowledge of object-oriented programming concepts. So, what are object-oriented programming concepts, why are they so special, and what documentation challenges do they create. This seminar answers your questions about the real meaning behind those job ads.

Gallagher, Susan W. STC Proceedings (1998). Careers>Writing>Programming>Technical Writing

Performance Ajax Tools

Wasting server resources can impact the performance of Ajax applications, resulting in excessive HTTP requests, high memory consumption, and the need for an unusual amount of polling to make applications work. Regular developerWorks author Judith Myerson suggests some open source tools and Firefox add-ons you can use to improve or solve problems with your Ajax applications.

Myerson, Judith. IBM (2008). Articles>Web Design>Programming>Ajax

PHP Coding Guidelines

The guidelines that I follow when writing my PHP scripts; can be helpful to have something like this if you're working on a joint project.

Waring, Paul. evolt (2005). Articles>Web Design>Programming

Powering Pipelines with JAXP  

The JAXP API allows Java programmers easy access to the power and flexibility of XML parsing and filtering and XSLT transformation. However, while many programmers utilize JAXP for simple XML parsing or single-shot XSLT transformation, going further to construct processing pipelines often proves difficult.

Nichols, Thomas. IDEAlliance (2005). Articles>Information Design>Programming>XML

A Primer of Object Orientation: What It Is and What It's Good For  

The computer industry is moving toward the adoption of the object-oriented approach as the standard mode of analyzing, designing, and implementing applications. This paper applies the new orientation to the task of simulating the traffic of people in a building. This paper is a primer to a new technology which promises to revolutionalize programming: object orientation. To make the presentation concrete, I will build it around a case history. Imagine that an architect asked you to create a simulation that will help her determine how many elevators anew building will need to keep the average wait for an elevator to, say, under thirty seconds. How would you go about this task?

Haltresht, Michael. STC Proceedings (1993). Articles>Software>Programming>Methods

Product, Process, and Profit: The Politics of Usability in a Software Venture    

In research and in practice,usability specialists commonly target the technology user-interfaces and help as the main arena for bringing about usability improvements. However, usability improvements depend on more than innovative and user-centered technical designs and implementations. Equally important for creating useful and usable software are the social and political forces that shape the development context. These forces give rise to leadership conflicts, factional disputes, renegade efforts, alliances and betrayals, all of which profoundly influence whether usability improvements will be supported and sustained within and across projects. This essay presents and analyzes a case history of a software start-up company in which usability achieved a Pyrrhic victory, triumphing only in the short run because of social and political forces.

Mirel, Barbara E. Journal of Computer Documentation (2000). Articles>Usability>Programming

Programming Hamlets

This tutorial illustrates various aspects of Hamlet programming as it provides a number of practical Hamlet examples. The examples are part of WebZEC (Web-based Zurich Event Console) -- a fast, browser-based console to quickly navigate in intrusion-detection alarms. With these samples, you can develop a good understanding how to use Hamlets for Web-based application development and how Hamlets work.

Pawlitzek, Rene. IBM (2005). Articles>Web Design>Programming

A Programming Primer  

The easiest way to gain the respect of programmers is to learn to speak their language. If you can do that, they’ll inevitably recognize the effort you've invested in learning to appreciate their work and will treat you as an equal thereafter. With that goal in mind, I present this glossary of key programming terms you should master.

Hart, Geoffrey J.S. Intercom (2004). Articles>Language>Programming>Glossary

Programming Web Services with SOAP

The task of creating and deploying web services is really not all that difficult, nor is it all that different than what developers currently do in more traditional web applications. The tendency on all platforms is to automate more and more of the gory details and tedious work in creating web services. Most programmers don't need to know the exact details of encodings and envelopes; instead, they'll simply use a SOAP toolkit such as those described here.

Snell, James, Doug Tidwell and Pavel Kulchenko. O'Reilly and Associates (2001). Design>Web Design>Programming>XML

Python and XML

Python and XML are two very different animals, each with a rich history. Python is a full-scale programming language that has grown from scripting world roots in a very organic way, through the vision and guidance of Python's inventor, Guido van Rossum. Guido continues to take into account the needs of Python developers as Python matures. XML, on the other hand, though strongly impacted by the ideas of a small cadre of visionaries, has grown from standards-committee roots. It has seen both quiet adoption and wrenching battles over its future. Why bother putting the two technologies together?

Jones, Christopher A. and Fred L. Drake. O'Reilly and Associates (2001). Articles>Information Design>Programming>XML

Reflections on an Icon Development Process: Managing Design  

Software organizations are increasingly willing to hire consultants in technical communication for projects in visual design. This paper examines ten factors critical to successfully managing icon development, based on experience in two different companies, Practical issues -defining the scope of the problem, recruiting the contractor and reviewers, writing the contract, deciding where the contractor should work, validating the images -- require attention to make your partnership with a consultant work.

Gould, Emilie W. STC Proceedings (1996). Articles>Graphic Design>Programming

The Role and Evolution of Design in Software Products

Design professionals often decry the lack of importance and investment their companies place on design. After all, most software projects revolve around a product's engineering, to the ongoing detriment of its design--not to mention the chagrin of so many designers, who wriggle uncomfortably toward the bottom of the food chain. But there is a good reason for this: products can be very profitable without investing a single penny in interface design--at least, beyond the user interfaces the engineers build. Indeed, at least in the early stages of a market or company, resources dedicated to intentional interface design are often a bonus rather than being viewed as a necessity.

Knemeyer, Dirk. UXmatters (2006). Design>User Interface>Programming

The Role for Technical Communicators in Open-Source Software Development    

Although it claims to adhere to user-centered design principles of participatory design and democratized technology, open-source software often fails to effectively address the usability needs of typical software users. In many cases, it embodies a system-centered design approach facilitated by the efforts of developer-users. In addition to the existing participation in open-source projects in the classroom, technical communicators should actively critique open-source software and promote user-centered design principles in open-source software projects.

Yeats, Dave. Technical Communication Online (2008). Articles>TC>Programming>Open Source

Running a Macro Automatically When a Document is Created, Opened or Closed

If you want a macro to be fired whenever any document is opened, regardless of which template the document is attached to, the simplest way is to write an AutoOpen macro and store it in Normal.dot.

Rado, Dave. Word MVP Site, The (2005). Articles>Word Processing>Programming>Microsoft Word

RUP and Goal-Directed Design: Toward a New Development Process

Interaction design methodologies, such as Goal-Directed Design, tackle the software development process from the top down by defining specific product requirements and interface behavior based on research and user needs. The Rational Unified Process (RUP) and other agile programming methodologies attack software development from the bottom up. RUP creates fluid efficiencies for iterating product development during the construction phase in order to react to changing product requirements while still producing shipping code.

Cronin, Dave. Cooper Interaction Design (2003). Articles>Project Management>Programming

Set up an Ajax Environment With a Scenario

Ajax (Asynchronous JavaScript + XML) is quickly emerging as a modern way of bringing desktop-quality software features to Web applications running on browsers. Open source software such as Linux-Apache-MySQL-PHP (LAMP) and open standards-based J2EE middleware, such as WebSphere Application Server Community Edition, provide excellent capabilities to develop and deploy Ajax Web applications.

Nathan, Senthil. IBM (2007). Design>Web Design>Programming>Ajax