A lightweight markup language uses syntax that is similar to wiki syntax -- keyboard characters are used to define formatting. This blog post argues that if your documentation needs are simple, and you have a low or non-existent budget, then a lightweight markup language might be worth investigating.
Visual Basic provides several hooks for easily connecting to WinHelp. In addition, you can call the WinHelp API from anywhere in Visual Basic for additional access to help. This document is intended to show you how to hook WinHelp to Visual Basic 5 and later without using add-ons.
In this article, we outline how IT analysts can effectively make determinations about the value of process documentation, and in the process, transform a potential scourge into a possible blessing.
Sometimes our developers are just a bit too eager. It doesn’t happen that often but when it does, it takes us Technical Writers by surprise. One such occasion happened today when the first build was created for the next release of one of our applications. No real issue there, but when they came to us half an hour after the build process completed to say the help didn’t look right, we went to investigate.
In the world of development, the need to track bug reports and enhancement requests are a given. But they're not generally required for documentation, in the way they are for code Quite the reverse. For documentation, bug reports and enhancement requests provide little benefit, and generally impede progress. This post compares documentation and code, showing why bug reports and enhancement requests are so vital to the code base, and at the same time why those reasons simply do not apply to documentation.
With the spread of new technology, technical communicators face interesting new challenges for solving documentation problems. One area of software development that technical communicators are increasingly becoming involved in is that of rule-based expert systems. Because of their complexity, both the systems and their documentation can be difficult to maintain. Technical communicators can solve some of these maintenance problems by flow-charting only the chaining structure of the rule-base design.
The biggest concern in software development environments is the retention of programmers. What they are really concerned about is the knowledge drain. These organizations know they need to capture this knowledge, but they do not want to do it themselves. They are turning to the writers who have always written the user manuals. These writers, most having no systems or programming background, must develop internal documentation for use in a programming maintenance environment. They do not know where to begin. This paper outlines a methodology for developing systems and programming documentation for programmers in a maintenance environment.
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.
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.
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.
This workshop teaches technical communicators what to include in internal documentation, how to interview and work with technical people, and basics of how to 'read' and evaluate code.
XML-based development projects often require the development of a Document Type Definition (DTD), which defines the XML code used in an XML document or application. Even if you are customizing an existing DTD like the DocBook DTD, documenting the DTD is a best practice for a number of reasons, including:Providing documentation
Standard UNIX commands can be combined into scripts. Such scripts permit the automation of tasks that otherwise may take many hours of manual work. The paper shows how scripts can solve such problems as putting messages online and indexing texts.
Documentation is a huge cost factor in software development, and companies are looking for ways to trim costs. If you cut back on product doc and customers don't complain, there's a temptation to keep cutting. Eventually you end up with software engineers writing bits of doc because all the tech writers were laid off, but there'll be one guy who didn't get laid off who has to work like heck to wire it all up and make it continue to look like professionally written doc.
Expert systems that use knowledge bases to find quick and accurate answers for customers are growing in popularity. Our experiences in writing knowledge bases for a large customer help desk have led us to believe that technical communicators are well suited for the job of “knowledge engineer.” We have used our technical writing skills to interview experts in an area, gather information from them, and then organize and write the information in a way that non-experts can use it.