#22907
By the time I stopped being President in 1993, the sense of computer documentation as a unified whole had ended. When one has such competent folks as Bill Horton writing entire books just on icons, you know that the days of single book coverage…or single SIG coverage were gone forever. Moreover, when the 20,000 member STC decides that it will focus on computers and writing, then the tiny 1200 member SIGDOC gets lost in the welter of talks, papers, presentations, and conventions. So it goes…
Brockmann, R. John. Journal of Computer Documentation (2001). Articles>Documentation>History
#22908
In the few short years that I have been connected with SIGDOC, the world of the technical communicator has changed quite a bit. These changes are visible in several major areas: in the work itself, in the technology and tools that the communicator uses, in the technologies about which they create information, in the work environment, and in the culture in which they operate.
Haramundanis, Kathy. Journal of Computer Documentation (2001). Articles>Documentation>History
#22905
In the mid 1970's, technical writers documented weapons of mass destruction for the military and its contractors. There were few computer-related jobs outside IBM and the other manufacturers. Corporate systems development managers did not know that people existed who were interested in such work.
Rigo, Joe. Journal of Computer Documentation (2001). Articles>Documentation>Collaboration>History
#22906
Back in these ancient days SIGDOC was a very relaxed organisation full of personal opinion, and hominess. To give you the flavour of that far off time, I shall present this report as a personal anecdote rather than a proper technical document. Please forgive me, those of you with more formal and well balanced notions of history.
Patterson, Diana. Journal of Computer Documentation (2001). Articles>Documentation>History
#30826
Simple Ways to Improve the Usability of Help
According to Jacob Nielsen's How Users Read on the Web, usability of web content can be improved drastically by making content more scannable. Many of his ideas would apply equally well to online help. So, how can technical writers leverage this information to make the help for their product more usable?
Helpscribe (2008). Articles>Documentation>Usability>Help
#27608
Single Source Information: An Agile Practice for Effective Documentation
In agile software development you want to travel as light as possible, and the easiest way to do that is to choose the best artifact to record information. I use the term 'artifact' to refer to any model, document, source code, plan, and so on created during a software development project. Furthermore, you want to record information as few times as possible, ideally only once. For example, if you describe a business rule in a use case, then describe it in detail in a business rule specification, then implement it in code, you have three versions of the same business rule to maintain. It would be far better to record the business rule once, ideally as human-readable but implementable code, and then reference it from any other artifact as appropriate.
Ambler, Scott W. Agile Modeling (2006). Articles>Documentation>Single Sourcing>Agile
#31167
Single-Source Documentation: Docbook versus DITA
When it comes to documentation projects, primarily technical, medical, and scientific, using XML is a no-brainer. The heavy thinking comes when deciding which flavor of XML to use: DocBook or DITA (Darwin Information Typing Architecture). I have been a steadfast supporter of DocBook for over six years. I'd tried my hand at DITA and gave it up as a fad; lots of bells and whistles, but too complicated to integrate. And couldn't DocBook do everything DITA promised anyway?
Mulvihill, Teresa. LiveTechDocs (2008). Articles>Documentation>Single Sourcing>XML
#24780
Single-Sourcing Online Documentation for Multiple GUIs, Languages, and Software Releases 
A small documentation team devised an innovative workflow to provide documentation for Interleaf publishing software for Windows and Motif, in English, French, German, and Japanese, using a single set of online source documentation. We used technology to streamline tasks, maximize communication, and optimize the documentation for future updates.
Bayer, Douglas, Rosalyn Reiser, Andrea Muren Shanahan and Margaret Waters. STC Proceedings (1995). Articles>Documentation>Single Sourcing
#30262
The Six Biggest Mistakes Project Managers Make with Documentation and How to Avoid Them
Professional business writers, such as technical authors, typically break a document down into small, discrete units of information, organised around a skeleton of topic headings. If you use this 'component' or 'modular' approach, you can plan and structure the document using the heading 'labels' that describe each section.
Pratt, Ellis. Cherryleaf (2007). Articles>Documentation>Planning>Project Management
#10576
Six Slick Tests for Docs and Help
Usability testing isn’t just for software and web sites. Testing documentation can ensure that it includes — and accurately conveys — all the information users expect and need. Testing gives you accurate information on how well your documentation and Help work. It can even uncover problems that are better solved by changing the interface.
User Interface Engineering (1998). Articles>Documentation>Usability>Testing
#24419
Six Steps for Successful Document Downsizing
By using the following method, the Mentor Graphics system management documentation and training group was able to achieve a 40% reduction in the size of the documentation needed to install and configure Mentor Graphics software. Not only did this reduction result in an approximate savings to the company of $50,000, but also produced a verifiable increase in customer satisfaction.
Tucker, Walt. STC Proceedings (1996). Articles>Documentation>Methods
#28316
Six Tips for Improving Your Design Documentation
Documentation is a crucial component of successful product planning and implementation, so it's important that it communicates as effectively as possible. 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.
Olshavsky, Ryan. Boxes and Arrows (2003). Articles>Documentation>Document Design
#25619
Six Tips for Improving Your Design Documentation
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.
Olshavsky, Ryan. Boxes and Arrows (2003). Articles>Web Design>Documentation
#20092
SmartStart Guides are a perfect vehicle for: convincing your clients that you are indispensable and irreplaceable; making money, staying challenged, and feeling creative.
Moster, Nancee. STC Proceedings (1997). Articles>Documentation
#21407
I admit that I don't know everything about subject-matter experts or SMEs (rhymes with please). But I do know that there are some things that you should avoid asking SMEs, the main ones being 'Does the user know this already?' and 'Do I need to explain this to the user?' The problem with these questions is that the SME is likely to reply 'No!' to both of them when in fact the answer is most definitely 'Yes.' SMEs tend to believe that everyone knows as much about technology as they do. Never, never, never let the SMEs tell you how to write the documentation. A SME is the subject matter expert, not the documentation expert (that's you).
Docsymmetry (2003). Articles>Documentation>Collaboration>SMEs
#30637
Social or Philosophical Issues Related to the Design and Delivery of User Assistance
User assistance is defined as a form of assistance that is provided to users of products to help them use the products more easily and efficiently. In the Information Technology industry, a product is a software product/application that users use to perform specific business functions. Users of these products/applications use them differently, based on their social and philosophical environment, their cultural context, their learnability and a number of other factors. While the same user assistance must necessarily be designed and delivered to the users of a product, because all users use a particular product/application to perform similar tasks, user assistance can be designed and delivered differently to users, based on their social and philosophical environment. This could enable users from diverse social and philosophical backgrounds use the same products/applications more effectively.
Das, Pradipto. Usability Interface (2007). Articles>Documentation>Usability>Help
#24657
Software Development Kit (SDK) Documents in 10 Simple Steps
Here are the ten simple steps to successful software development kit (SDK) documentation.
Buck, Catherine. KeyContent.org (2004). Articles>Documentation>SDK>Technical Writing
#27584
Software documentation or source code documentation is written text that accompanies computer software. It either explains how it operates or how to use it. In fact, the term software documentation means different things to different people. This article describes the term as used by the largest groups of users.
#20556
Software Documentation Process - McGraw-Hill School Systems
This panel presents the software documentation processes of three companies. At McGraw-Hill School Systems, the technical writers are involved in every stage of the software development life cycle. This approach ensures that writers are always in control of the information they need and that sufficient time is available for the documentation process. Our involvement allows us to produce high-quality documentation that is up-to-date with the software’s functionality.
Rogers, Anne E. STC Proceedings (1996). Articles>Documentation>Workflow>Collaboration
#24612
Software Documentation Process-Datastream Systems, Inc.
This panel presents the software documentation processes at 3 companies. At Datastream, a software development company with approximately 200 employees, we, the technical writers, have integrated ourselves into all stages of the software development process. Additionally, we have incorporated the tenets of document cycling into our documentation process. In this paper and in our presentation, we outline our documentation process. We do not prescribe our approach but instead hope that it sparks a dialog among software documentation writers in similar companies so that we may learn from each other.
Jeansonne, Jerold and Amy J. Listeman. STC Proceedings (1996). Articles>Documentation>Workflow
#20555
Software Documentation Process: Symbios Logic
This panel presents the software documentation processes of three companies. Participating on an interface design team allows writers to contribute to a software’s usability and to develop supporting documentation early in the software’s development cycle. This presentation summarizes the crossfunctional team’s process and strategies for designing the interface and for preparing usable support products. I will also review the successes and problems we encountered as we created online help and a printed user guide. Writers can learn about Symbios Logic’s interface design team as one approach to creating usable software with accurate, quality documentation. At Symbios Logic, one of our goals is to develop data storage products supported by accurate, easy-to-use documentation. The major challenge we face in completing this documentation is meeting the release dates for our products. To achieve this goal, we are re-designing our latest software by combining both interface and documentation development into one design process.
Burroughs, Dia H. STC Proceedings (1996). Articles>Documentation>Writing>Technical Writing
#21382
Software Usability and Documentation
This article shows how a user-centred approach to software design can reduce the requirement for documentation. It lists Jakob Nielsen's usability heuristics, and for each one, shows how following the heuristic can reduce the requirement for user documentation.
Unwalla, Mike. TechScribe (2003). Articles>Documentation>Software>Usability
#26720
Software User Assistance Project Management
This article takes a look at a methodology for developing and managing a Software User Assistance (UA) System, a way of doing things in a structured manner. It provides a complete walkthrough for managers responsible for designing, developing, and managing a software product’s user assistance system. The software’s UA system could comprise of both paper-based user manuals and online help systems.
Ferris, Tamara. Klariti. Articles>Documentation>Usability>Help
#18887
A Solution to Writing Winning Sales Proposals and Other Sales Documents
This article explains how we built a solution to producing sales proposals and other sales literature for our own company using an affordable content management solution.
Pratt, Ellis. Cherryleaf (2003). Articles>Business Communication>Single Sourcing>Documentation
#30574
Some Stategies for Addressing the Changing Audience
'Know your user!' is the first thing every aspiring technical communicator learns. Everyone agrees that understanding the technical skills and needs of your audience is essential to producing high quality technical documentation. However, knowing exactly who your audience is and what they need from documentation is no longer an easy task. The increase in international markets, multiculturalism in America, end the number of people using software products for the first time all mean that the audience you knew so well a short time ago may not be the same audience using your documentation today. As technical communicators, we can no longer assume that our users' language and technical skills remain stable over a long period of time. How to assess and meet the needs of a changing audience is a challenge many technical communicators face today.
Lopes, Jeff and Kimberly E. Willis. STC Proceedings (1993). Articles>Documentation>Audience Analysis>Usability
