Can Lightweight Markup Languages Be Used for Documentation?

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.

DMN Communications (2008). Articles>Documentation>Programming>Wikis

Dealing With an IT Scourge: Process Documentation  

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.

Schiesser, Rich. TechRepublic (2005). Articles>Documentation>Programming>Project Management

Documenting the Flow of Rule-Based Programming in Expert Systems  

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.

Glover, Kyle S. STC Proceedings (1994). Articles>Documentation>Programming>Workflow

How to Approach a Systems and Programming Documentation Project  

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.

Glick-Smith, Judith L. 'Judy'. STC Proceedings (1998). Articles>Documentation>Programming

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

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

Systems and Programming Documentation for Technical Writers with No Data Processing Background  

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.

Glick-Smith, Judith L. STC Proceedings (1993). Articles>Documentation>Programming>Software

Tips for Documenting an XML DTD  

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

Kelly, William T. TechRepublic (2003). Articles>Documentation>Programming>XML

Using UNIX Scripts to Put Documentation Online  

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.

Haltresht, Michael. STC Proceedings (1993). Articles>Documentation>Programming>UNIX

Writing for Expert Systems: A New Frontier for Technical Communicators  

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.

Casey, Margot B. and Joan Lohmann. STC Proceedings (1995). Articles>Documentation>Programming

Where Did All the Documentation Go?

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.

assertTrue (2009). Articles>Documentation>Programming>Technical Writing

Docs Aren't Code

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.

Armstrong, Eric. Sun Microsystems (2008). Articles>Documentation>Programming>Technical Writing

Five Tips For Documenting Code 

If you want to get better at documenting your own code then this is the post for you. I have 5 simple tips to follow while coding to make the process easier.

Inside RIA. InsideRIA (2009). Articles>Documentation>Programming>Flash