Abstract
The role of communication is central to any software development. The documentation forms the message carrier within the communication infrastructure of a software project. As software development processes shift from predictive to adaptive environments and serve an ever more hardware diverse demographic, new communication challenges arise. For example, an engineer may want to be able to remotely author a document in a shell environment without the need of any special purpose software, port it to different computer architectures, and provide different views of it to users without making modifications to the original. However, the current state of affairs of software documentation is inadequate to respond to such expectations. In this article, we take the position that the ability of documents to be able to communicate at all levels intrinsically depends upon their representation. The rest of the article proceeds as follows. We first outline the background necessary for later discussion. This is followed by a proposal for a quality-based framework for representing software documentation in descriptive markup and application to agile software documentation. Next, challenges and avenues for future research are outlined. Finally, concluding remarks are given.
TopDescriptive Markup And Representation Of Software Documentation
We look at a software document from two viewpoints, namely that of a producer and that of a consumer. Based on that, the representation requirements that we consider pertinent for software documentation are the following:
Key Terms in this Chapter
Agile Document: A customer-oriented lightweight document that need not be perfect but just good enough.
Knowledge Representation: The study of how knowledge about the world can be represented and the kinds of reasoning that can be carried out with that knowledge.
Document Engineering: A discipline that is concerned with principles, tools, and processes that improve the ability to create, manage, and maintain documents.
Ontology: An explicit, formal specification of a conceptualization that consists of a set of terms in a domain and the relations among them.
Single Source Approach: A technique that encourages a once-only creation of a resource, such as a document, in a manner so that it could be reused or repurposed for different contexts.
Descriptive Markup: A model of text that focuses on the description of information using markup delimiters for consumption by both humans and machines.
Semiotics: The field of study of signs and their representations.