Here you will find all the definitions that are scattered throughout Skriftlig Info.
See DITA Bookmap
A "call-out" is an arrow that points to an object in the graphic element to identify this object. At the other end of the arrow, the object can be identified with verbal text, icons or symbols, or optionally with alphanumeric characters.
DITA (Darwin Information Typing Architecture) is a standardized data model, method and architecture for writing and publishing topic-based information. DITA uses XML (Extended Markup Language). With the help of "tags", each element in the text is identified. Mechanisms in DITA facilitate extensive reuse of multimodal text. The structure of a DITA publication uses one or more topic maps to connect the topics in the right order. The XML code contains no information about the layout and presentation, as the stylesheets handle this.
A DITA bookmap is a stand-alone data module that contains electronic links to DITA topics and other topic maps. The module is set up with the same structure as we find in a traditional book. The bookmap determines the order in which the information is to be presented. It also defines structure by nesting topics and topic maps into each other. The top-level topics in a bookmap are referred to as chapters. The bookmap can include a table (relationship table) which defines relationships between the various topics.
A DITA Concept topic is a stand-alone data module containing multimodal text. The module has a title and enough information to convey the necessary information about a task, a process or another similar concept. The information must support the understanding of the tasks that the product performs. A concept topic should thus provide a simple description that help the reader to understand a product's basic characteristics, operation and functions.
A DITA library topic is a stand-alone data module that contains multimodal text. The module is created using a standard, non-specialized DITA topic. The text fragments contained in the library can be reused in multiple DITA topics using the mechanisms in DITA. The most common mechanism for retrieving information from a library is the <conref> element.
A DITA Reference topic is a stand-alone data module containing multimodal text. The module has a title and enough information to convey the necessary detailed information about something the reader may benefit from in connection with an topic, but does not necessarily need to remember. The information must convey fact-based information to support the understanding of the tasks that the product performs. A reference topic should thus convey detailed descriptions that can be retrieved when necessary to help the reader understand a product's technical specifications or basic functionality.
A DITA relationship table is a function which, in the form of a table, establishes electronic links between DITA topics. The relation table must be located in a topic map. The relational table uses rows and columns to link the topics together. The linking only occurs horizontally between topics in the same table row.
A DITA Task topic is a stand-alone data module containing multimodal text. The module has a title and enough information to explain a specific procedure. A task topic must only explain one task, and this must be explained in an easy-to-understand manner with a fixed structure. Each action must be explained in the imperative tone with numbered steps. Each step in the procedure shall contain only one action and appear in the order in which they are to be performed.
A DITA topic is a stand-alone data module that contains multimodal text. The module has a title and enough information to explain a specific procedure or concept. Each topic is written in such a way that it is independent of other topics and can be reused in different publications whenever appropriate. The content of the topic is presented in a flat structure. Structure and context are established when the topic is inserted into a topic map together with other topics.
A DITA topic map is a stand-alone data module that contains electronic links to objects. Such objects are DITA topics and other topic maps. The topic map "connects" these objects together. The topic map determines the order in which the information is to be presented, and defines structure by placing topics and topic maps inside each other. The topic map can include a relationship table that establishes links between the various topics in the topic map. Topic maps can also define values for variables.
An empirical reader is the generic recipient of a text. The reader has no special characteristics that place them in any particular target group. We must regard this reader as a passive participant in the communication. The empirical reader adopts a pragmatic attitude towards the text.
A graphic element is a multimodal text element that primarily consists of a graphic presentation of a photograph, illustration or screen capture. In digital publications, the graphic element can also contain video, animation and sound. Graphical elements can have different sizes, technical designs and formats. They are normally adapted to the format in which the document is published.
A globally unique identifier (GUID) is a 128-bit hexadecimal code used to identify objects in computer systems. Normally, the code is established automatically by the computer system using a dedicated code generator. The GUID code appears as a very large number. The size implies that the probability that a GUID will be duplicated is close enough to zero to be negligible. The term universally unique identifier (UUID) is also used.
The general term illustration is used to describe a photograph or technical drawing created for use in a technical specification or procedure. The illustration can be hand-drawn, scanned, photographed, post-processed, or created on a computer in vector or bitmap graphics. The illustration may contain text and symbols.
The term indirect addressing is used when an object is retrieved into a topic or topic map using an additional "layer" in the publication. Where the object would normally be addressed using a direct link to a specific location in the repository, the link is replaced with a pointer to a specific topic map in the publication. This topic map directs the link to an optional source. The mechanism in this topic map uses the keys attribute. For this reason, the process is often called key-based indirect addressing.
An information element (in other contexts also called data capsules or modules) is an independent data module in a suitable format. The module contains multimodal text organized as text fragments. There are no restrictions on the information element's content or scope. The element can be reused in different contexts. The use of information elements requires that reuse takes place by electronic linking in a tool that supports such functionality.
A line-replaceable unit (LRU) is a specific part (module or component) that can be replaced relatively quickly when the product fails. Replacement of the part can occur where the product is in daily use. The product's maintenance philosophy determines which parts are "line-replaceable units" and who can carry out the work.
A maintenance manual (often referred to as "Service manual", "Repair manual" or "Technical manual") is a technical publication related to a specific product or a group of similar products. The manual shall provide information, instructions and recommendations for safe and efficient testing, troubleshooting and parts replacement.
A product's maintenance philosophy is the mix of strategies that ensure that the product works as expected when needed. The philosophy defines how the product can be maintained, who can carry out maintenance and replacement of parts, what they can do, and where they can or should do it. The responsibility for defining the maintenance philosophy lies with the product manager (or equivalent).
Within maintenance philosophy, the term maintenance aids describes digital and interactive verbal tools generated by the product, as well as information in the end-user and service documentation. Together, these tools can assist maintenance personnel in testing, troubleshooting, and repairing the product.
The term Mean time between failures (MTBF) is used for mathematical calculations that will calculate the statistical lifetime of a given component or module. In this context, the phrase "lifetime" is used to measure how long the device is operational under normal conditions before it breaks down.
Metadata is information about the information. This data does not appear as part of the data in a given object, but is linked to the object with other mechanisms. Metadata can for example convey information about the object's content, belonging and origin. Metadata can also contain information of a more technical nature. Which kind of metadata that is linked to a given object depends on the nature and properties of the object. The information in the object's metadata is used for organisation, structure and retrieval (search).
A model reader is a fictional person who represents the empirical readers in your target audience. The model reader should personify your product's "typical" reader and user. The person can be created by your own imagination or based on real people. He or she must be given relevant and concrete qualities and knowledge that enable you to "sharpen" your message. The model reader is thus "...a type of reader that the text not only assumes as a collaborative partner but that it also strives to create" (Umberto Eco, 1994).
Modular writing is a methodology where you divide a given multimodal text into larger or smaller parts. You can open and edit these parts separately and reuse them in different contexts. The methodology assumes that reuse takes place by electronic linking in a tool that supports such functionality.
A multimodal text (also called "composite text") is a text in which several different forms of expression are used. Such forms of expression include text, tables, images and illustrations, and - in interactive publications - film and sound. Such forms of expression are called modalities. The text is thus multimodal.
The general term photo (or photograph) is used to describe an image from a camera or a still image from a video, which is created for use in a technical description or procedure. The photo was taken with suitable equipment (camera, telephone, film camera), and it can be post-processed in a suitable editing program. A photo does not contain text or symbols.
When you use profiling (also: conditional text) on a text, a profile (also: condition) must be defined. This profile is added to the text with a logical condition in the form of a value. Each value defines the property or affinity that is added to the information. By selecting corresponding values in the publishing phase, you can either include specific information in the resulting book or remove information that should not be included.
When you use profiling (also: conditional text) on a text, a profile (also: condition) must be defined with one or more values. These values must be regarded as logical conditions. While the profile's name is fixed, different values are used to give the text property or affinity. By selecting the corresponding profile and value in the publishing phase, you can either include specific information in the resulting book or remove information that should not be included.
Profiling (also: conditional text) means that a given text fragment is given one or more logical conditions in the form of defined values. These values define a characteristic or attribute that is added to the information. By selecting corresponding values in the publishing process, you can either include specific information in the resulting book or remove information that should not be included.
Reuse is defined as the electronic recontextualization of separate information elements (multimodal text fragments). The information elements must be established as separate data files or as addressable elements in a source file. The elements are inserted into one or more of the main documents using electronic references (links). In the event of changes to the source file, the information in all the main documents will automatically change accordingly.
|
The rhetorical situation (in rhetorics) |
The expression rhetorical situation means the circumstances that exist when the reader is to consume a text. Such circumstances may, for example, include the reader's physical location, the environment, and the tasks the reader needs to do while he reads the text. The rhetorical situation also covers considerations related to language and culture.
A screen capture (or screenshot) is a graphic element that appears by taking a copy of all or part of the presentation on a computer screen. The screen capture can be post-processed in a suitable editing program.
A shop-replaceable unit (SRU) is a specific part (module or component) that can be replaced when the product fails. Replacement of the part must take place at a suitable workshop. The product's maintenance philosophy determines which parts are "shop-replaceable units" and who can carry out the work.
A stem topic is a stand-alone data module (normally a concept topic) that only contains a title (<title>) and possibly a short introduction (<shortdesc>). The stem topic is used to establish a stand-alone heading at the beginning of a chapter or a set of topics. The stem topic is brought into the subject map using <chapter> or <topicref>, and the structurally underlying modules are nested into the topic. The term "stem topic" is not defined in the official DITA standards.
|
Define the target group for your publication |
The term target group is used to define the collection of people who will be the recipient of a message. To belong to a target group, members must satisfy selected common criteria, such as gender, education, age and place of residence. A target group can also consist of organizations or companies, in which case the criteria differ. All communication must occur on the recipient's terms and meet the conditions laid down by the target group's common criteria.
Task analysis is an analytical process to acquire relevant knowledge about which tasks the product's users want it to be able to perform and which tasks the manufacturer has developed it to perform. The analysis should organize the tasks by relevance according to the product's primary functions and characteristics. The analysis should define to what extent descriptions and relevant reference information must be included in the user manual.
In technical documentation, the term task-oriented writing is used for a methodology where the information is organised as much as possible as procedures. These describe how a product should be used. The methodology is based on recognising that the reader is primarily interested in knowing how tasks are performed and only secondarily interested in knowing how something works. The procedures included in a given publication are based on a task analysis where the author has acquired relevant knowledge about which tasks the product's users want it to be able to perform and which tasks the product has been developed to perform.
See DITA Task topic
The term technical documentation is used as a collective term for several document types that contain information about how a product is developed and how it should be manufactured, tested and maintained. Therefore, drawings, photographs, procedures, specifications and corresponding information are considered technical documents. The documents are published in several different formats adapted to the given purposes.
The term technical manual describes a document prepared by the manufacturer to explain to technical personnel how to install, maintain and repair a given product. A technical manual can be published in several formats adapted to the reader's situation and needs.
A text fragment denotes each individual component of an information element. The text fragment consists of a multimodal text, and can for example contain a word, a sentence or an illustration. As part of the information element, the fragment can be reused in different contexts. Reuse takes place by electronic linking in a tool that supports such functionality.
In technical documentation, the term topic-based authoring is used for a methodology where the content of a publication is structured in independent topics. Topics can be used in any order within a given publication and reused in other publications. The text in each topic should not assume that other topics are known to the reader and should not relate to others. Context is achieved by publishing different topics in a given order, preferably linked with hyperlinks.
See DITA Topic
See DITA Topic map
The term user manual is used to describe a document prepared by the manufacturer to explain to the end user how to use a given product. A user manual can be published in several formats adapted to the reader's situation and needs. Software is often supplied with content-sensitive online help, where the user manual is published in an interactive format.
A variable (often referred to as text entity, variable or keyword) is a independent fragment that contains a value in the form of a text. This fragment can be defined as part of the meta information of a given publication, or in one of the underlying files used by the publication. The fragment is electronically linked into a given context, and will there display the defined value. By changing the variable's value, all instances of the fragment in the publication will automatically change to show the new value.
The term variable (often referred to as text entity, variable or keyword) is used as a proper name to identify the independent fragment that can be reused in the texts. This name does not change. The variable has a value. The value is the text that the variable contains. It is this value that appears in the text in the publication.
XML (eXtensible Markup Language) is a hardware-independent data format used to store and manage information. XML does nothing, but it identifies the information using "tags". The focus in XML is what the information is, not where and how it is used. XML is used to create documents, software and information systems.
All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.
The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.