This series that I have decided to dub ‘Academusings’ provides a more theoretical take on subjects related to technical writing and structured authoring than my usual advice. I figured that it would be interesting to apply my studies in subjects like the philosophy of language, cultural evolution theory, and cognitive linguistics to these topics. This first piece will concern itself with reusability. Specifically, I will consider whether you should anticipate the differences in context for the same content in some way.
The main claim of this piece is that you can account for and mitigate such potential contextual effects with a variety of methods. For example, you can use controlled language where the exact specifications are provided by some specific external standard, an accessible internal standard, or as part of the content itself. To some extent, this is already a part of the standards for technical documentation. However, the discussion here specifically focuses on the relationship between such practices and the risks related to different contexts when content is reused as part of structured authoring.
Please note that this piece is not intended as the equivalent of a journal article in terms of academic rigour. The characterisations of different theories, for example, correspond to my understanding of them and these descriptions have not been actively cross-referenced with the relevant literature. This piece is more comparable to a draft for a research plan. It thus includes speculation that is yet to be (dis)confirmed through actual research on the subject.
Hypothesis
No theory of meaning entirely denies that context affects the meaning of utterances, including the contents of texts. They only vary in term of what kinds of contextual effects they posit and how important these kinds of context-sensitivity are considered. As such, regardless of the details, context has an effect on the meanings that users can and will derive from technical documents.
Structured authoring, specifically, involves the use of the same pieces of content in different positions. The context for these pieces of content includes the surrounding document. The reused content itself also affects the context for the rest of the document in return, although this aspect of this relation is left largely unaddressed here. Thus, if the types of contextual effects that these changes in context incur can affect the experienced meanings of these pieces of content, it is important to control their impact.
The approach that I expect to work best to control the relevant contextual effects involves providing a controlled local context that is kept constant across all documents in which the same components are used. This context can act as an anchor that standardizes specific contextual effects across positions. In effect, even if the general conditions required for a context-insensitive theory of meaning were unachievable, these conditions could be implemented locally to make what the models that such theories posit applicable.
This approach can then be complemented with methods that also control for the remaining kinds of contextual effects that all theories of meaning recognize. For example, all indexing expressions can either be limited to the scope of the reused piece of content itself or be replaced with non-indexing expressions. The use of invented proper names instead of the definite article is one such method.
Theoretical Framework
The theoretical framework in terms of philosophy of language which I will apply throughout largely aligns with contextualism. While such considerations are not strictly tied to any specific theory within that approach, my take is largely informed by relevance theory. However, as the ideal for technical writing aligns more closely with claims made by invariantists, I will also discuss whether the relevant contexts can be controlled in ways that produce such results. Invariantism (also known as literalism) will primarily be represented by semantic minimalism in the context of this piece.
Contextualism and Invariantism
A major disagreement on the nature of meaning in the philosophy of language concerns how pervasive contextual effects on meaning are. According to the different varieties of contextualists, the effects of context ground how we approach the act of interpreting language (and other signs). In effect, you cannot determine a baseline that exists independently of all contexts. Instead, there will always be conceivable contexts in which the ascribed meanings share no invariant base meaning.
Meanwhile, the historically dominant approach called either invariantism or literalism is founded on the notion of there being some degree of proper meaning which spans all conceivable contexts. Even when the proponents of such theories accept that contextual modulation of meaning exists, they argue that such modulation only occurs in relation to this baseline from which interpretation must always proceed.
For more information on the subject, see Recanati (2003), for example.
As stated, this piece will proceed under the assumption that (some form of) contextualism is largely correct. In so doing, it will address risks associated with this possibility in the context of structured authoring.
As an illustration of the difference between these two approaches, consider the following statement:
‘Tighten the screw.’
In the context of an assembly manual, these words mean that a piece with a spiraling raised metal edge along its length must be turned until you feel a sufficient level of resistance.
In the context of a non-assisted interrogation, these words mean that more forceful coercion must be applied to the person being questioned to make that person state what the interrogators want to hear.
One theory in relation to each approach is introduced below to show the differences in how they would frame these two scenarios and the underlying semantic processes.
Relevance Theory
Relevance theory is among the more influential contextualist theories. It was originally formulated by Dan Sperber and Deirdre Wilson in their 1986 book Relevance (revised in 1995).
According to relevance theory, cognitive interpretation processes are guided by the optimization of contextual relevance. Such relevance is approximately the sum of associated cognitive effects — or, the sum of absolute values for changes in experienced degrees of confirmation for a set of beliefs. As these formulations hint, defining ‘(cognitive) relevance’ in a robust way which does not beg the question has been a challenge for the proponents of this theory. In slightly simplified terms, relevance is how much a given interpretation impacts your understanding of a subject matter to which you are attending. Both further confirmation of prior assumptions and challenges to them qualify as long as the total effect is larger for the processing effort that it takes than comparable alternatives.
Thus, while there is a contribution that the available proper meanings, as understood by the people involved, provide, this contribution is simply one parallel factor among many. According to relevance theory, people process which competing proper meaning to associate with an utterance in a manner informed by the context. They do not derive a proper meaning and then either deem it appropriate for the situation or search for a more contextually appropriate alternative interpretation.
In an assembly manual, for example, the recognized context of use and reason for consulting the manual all but ensure that the phrase ‘Tighten the screw’ will be understood as referring to using a tool to turn a screw tighter.
However, abnormal contexts can modify this associated meaning in manners which are not derivative of any ‘literal’ reading of the phrase.
Someone with paranoid or otherwise psychotic thought patterns could well understand the same phrase through its (generally) secondary association. They could, for example, believe themselves to have intercepted a message between conspirators that tells the recipient to make life harder for this person.
Similarly, if the person was in fact a part of some conspiracy and they had reason to assume that the manual was being used to convey their instructions, they would likely interpret the utterance as a command to make life harder for some designated target. Even in the absence of some explicit cipher, if they assumed that the manual had been delivered by their superiors and if they perceived some otherwise unexpected detail about the phrase (such as slightly inconvenient placement or a printing error on the same line), they could default to this interpretation as a result of optimizing expected relevance.
Also note that the notion that ‘tightening the screw’ means ‘putting on pressure’ need not be derived as a figurative reading by the subject. Despite any such objective history, any given individual may simply have encountered the same phrase in different contexts with different available interpretations and come to associate it with those patterns.
For more information on relevance theory, see Wilson and Sperber (2004), for example.
Semantic Minimalism
Semantic minimalism is used here as the representative of invariantism. This theoretical framework shares the focus on the cognitive processing of meaning that defines relevance theory. As such, it constitutes a good point of contrast with that theory. Additionally, it provides a realistic goalpost for the ideal level of unambiguity that technical writing may achieve through the engineering of appropriate contexts. A major modern proponent of semantic minimalism is Emma Borg who has defended the theory in, for example, Minimal Semantics (2004) and Pursuing Meaning (2012).
The minimal invariant semantic contribution that semantic minimalism claims each word to contribute is a thread that explains why the same word can have novel applications in various contexts yet remain understandable. This does not apply to homonyms which are accidentally identical such as ‘bank (as an institution)’ and ‘bank (of a body of water)’. However, it would explain why terms such as ‘hammer (v)’ can apply both to nails and to points. In each instance, the verb denotes a shared minimal concept such as ‘to forcefully push in through repeated application of suitable vectors’. This notion may not fully correspond to the usual understanding but it accounts for the available extensions of standard usage.
The challenges that this approach faces include sufficiently accounting for possible applications proactively and explaining how such minimal concepts are cognitively available to enough people.
It is very tempting to adapt the posited minimal concepts retroactively to account for new data. However, reliance on such retroactive changes deprives the theory of all explanatory power. You can always formulate a new minimal concept to account for possible counterevidence. Instead, there ought to be some means of specifying the contents of these concepts which does not rely completely on linguistic samples.
There is also a level of friction involved in positing concepts that are both invariant and grounded in cognition. How do (enough) people acquire sufficient approximations of such concepts, especially given how they do not correspond to intuitive notions? If acquiring these concepts relies on learning, why would individuals acquire the minimal concepts rather than more substantial concepts that suit the specific linguistic samples available to them? If these concepts are instead treated as innate, there are other obvious issues such as how to account for concepts that are of no evolutionary benefit and cannot be derived from evolutionarily relevant basic concepts.
According to this theory, then, utterances of ‘tighten the screw’ would always have a minimal logical form derived from the minimal meanings of its constituents, ‘tighten’, ‘the’, and ‘screw’. Thus, both in the context of a manual and the context of an interrogation, people would first account for this minimal meaning and then process the effects of any contextual factors which complement it. Such a minimal meaning would likely resemble what is expressed by ‘twist the thing that determines the level of free movement available to connected entities to increase the pressure that it applies’. While the formulation thus expressed is inelegant, it only represents a translation of a conceptual aggregate into natural language.
For a summary and further resources on different forms of semantic minimalism, see Vicente (2017), for example.
The Problem: Reuse in Changed Contexts
Structured authoring allows the reuse of the same content in multiple contexts. This ensures uniformity in terms of the used technical expressions, for example, and you can update all use cases at the same time by changing one content module. Such support for reusing content is thus a major benefit of structured authoring. It minimizes errors involving inconsistency and the time required to update specific details.
The more varied and penetrating contextual elements are, the greater the risks involved in reuse of content become. Thus, if contextualist claims are largely correct, one must account for the associated risks to reduce the available patterns that result in critical misunderstandings. Such differences in available interpretations are not limited to fanciful thought experiments. For example, content references for note elements may include terms such as ‘tighten’ or ‘wait’ that imply an appropriate threshold. If the appropriate threshold is not stated explicitly (e.g. ‘until you hear a click’) for reasons such as how said content must be generic enough to remain appropriate for all its intended applications, then determining the exact action to take is subject to contextual considerations.
Similarly, if a content module was originally written directly for a specific application such as a user manual, it may contain the indexical use of definite articles in reference to objects discussed in preceding parts of that document (e.g. ‘test the valve’). However, issues with indexical expressions are a more general consideration that involves little contextual penetration. Even if more radical contextualist claims were deemed untenable, some issues involving reuse of content and changes in context would remain.
Of course, all such issues are avoidable — and the means to facilitate that are a subject discussed below. They can still proliferate under specific circumstances unless they are addressed.
The Proposal: Control Contextual Effects
The first step is to recognize the possibility that differences in context across applications may introduce relevant changes in how users interpret the same content.
The second step is to address such contextual effects.
While it is impossible to make the different contexts of application identical by virtue of the fact that they are different applications, it is possible to control specific contextual factors through various means. Such standardization then generates contexts which are similar enough in relevant respects to avoid issues. In effect, when all the relevant contexts are suitably engineered, they provide a level of uniformity which would support semantic minimalism locally even if contextualists were correct about meaning in general.
Below is a list of different methods that help control contextual effects. Many of these methods are not new. However, it is worth considering if they are worth implementing to reduce the discussed risks if they are not currently in use as part of your documentation practices.
Controlled Natural Languages
Controlled natural languages are constructed variants of natural languages such as English where the allowed grammar and vocabulary are restricted with specific goals such as reduced ambiguity in mind. Despite such standardization, they remain natural languages rather than formal languages.
For purposes of technical documentation, there exist some pre-established standards which you may adopt. However, it is often necessary to adapt those standards to suit the specific needs of your documentation. The considerations involved in constructing local standards are thus discussed separately below.
External Linguistic Standards
You can commit to specific formal standards to codify the meanings of expressions more strongly than natural language allows. In the context of technical writing, a common standard would be ASD-STE100. It is the baseline standard for simplified technical English from which more specific applications are derived. The standard consists of a set of rules for writing and a standardized dictionary of allowed expressions. The rules for writing such as ‘restrict sentence length to no more than 20 words (procedural sentences) or 25 words (descriptive sentences)’ are mostly universal. Because the dictionary was written with aerospace industries in mind, it must be adapted to some degree for applications such as software development.
The expected effect of external linguistic standards is that the expressions are not subject to the usual contextual modulation in terms of their meaning. They formalize the meanings of expressions in natural languages. For example, simplified technical English only allows the term ‘deploy’ to be used to in the sense ‘to move or cause to move from a specified position of storage and into operation’. In contexts where STE is applied, the definitions of this terms do not thus include its usual, more general sense of ‘to put something into use’.
How effective external linguistic standards are as a means of controlling contextual effects depends on the specificity of the associated definitions. Not all standards are equally rigorous. Additionally, if contextualism is correct, no degree of specificity in terms of definitions eliminates the possibility of contextual penetration. These measures are only a matter of restricting such effects to a manageable level where they do not risk critical miscommunication in relation to technical documents.
For more information on the effectiveness of STE, see Göpferich (2019), for example.
Meanwhile, Galinski and Giraldo Pérez (2016) discuss general rules for standardizing language like this.
Internal Linguistic Standards
You can also establish internal linguistic standards that only apply in the context of your documents instead. Such standards must be conveyed to the users of those documents for them to have any effect. Definition lists are a conventional method to provide users with such local definitions. You should define all complex technical concepts such as ‘access controller’. However, you can also add application-specific definitions for common concepts.
When there is at best an approximation of a suitable external standard for a specific application, you can use definition lists to adapt such a standard. For example, STE defines ‘select’ as ‘make a choice’ and it is the only expression that is allowed to express this notion. However, in the context of software, ‘select’ standardly means ‘mark a part of the interface for purposes of an operation’, such as when you select a string of text to apply text effects to it. Thus, while an approximation of STE can be used in the context of documents related to software, it must be adapted to account for such conflicts. Definition lists can make any such changes explicit to the reader, even when they codify common concepts.
The principle for restricting contextual effects is the same as with external linguistic standards: you exclude alternative interpretations that the terminology would otherwise afford. The difference is that the definition list is specific to your documents and can be included as part of them to help users. You can obviously also adapt parts of standards such as STE into a definition list to convey them directly like this.
For an example of the considerations involved in an early form of application-specific controlled technical English, see Hayes, Maxwell and Schmandt (1996).
Knežević and Chiarello (2013) also provide a case study where they recommend controlled technical English to prevent maintenance errors.
Condamines and Warnier (2017) discuss how to ground controlled natural languages on subject experts’ example and the limitations that such languages can have in large-scale projects.
Laís Neves, Hori and Torres (2011) discuss how controlled natural languages can be implemented to help formulate use case scenarios in TaRGeT for product testing in software development.
Explicit Specifications
Controlled natural languages provide an increased degree of specificity for terms through the definitions included in either external or internal dictionaries. It is also possible to provide such specifications as part of a situation where a term is used. This is especially useful when the specifications are precise or when they vary from situation to situation. In terms of tightening a screw, such specifications could include the exact number of rotations, for example.
The effect of such specifications in terms of contexts is that they provide an immediate context that restricts the possible interpretations for otherwise open-ended concepts. Such context is not limited to preceding text, either. Parts that come after may reframe or modulate the meaning of a preceding expression. While this is true more generally as proven by the effects of plot twists in literature, in technical writing, it is best to restrict yourself to immediately accompanying contexts for such specifications.
Fitchett and Haslam (2002) provide an introduction to writing specifications in general. Their work is not limited to this sense but it ought to prove helpful in designing and formulating such specifications as well.
Covey and Faber (2002) provide practical guidelines for formulating technical specifications.
Stalnaker (1998), for example, discusses the kind of context that such situational specifications help provide.
Use Scenario Analysis
A part of the context of the end user of a document are the details of the situation in which they do so. For technical documents, such situations can be anticipated to an extent where you can trust in the presence of various factors. For example, when the user consults the maintenance instructions for a specific component, you can generally assume that they are in the presence of said component or have (cognitive) access to its details.
When you analyze use scenarios for your documents, you make an inventory of the expected scenarios and the characteristic elements of each. Such elements should include the objective conditions around the user. They can also include the expected personal characteristics or state of the user when such details can be anticipated and they are relevant for how they are likely to perceive the document. For example, a user under the stress from a high risk scenario may require the summary statements of five or fewer words for each task to be highlighted.
One approach to this task is to treat the relevant conditions as affordances: opportunities for the user to enact their capabilities, including cognitive capabilities. This concept expresses the relation between specific types of bodies and the specific environments that these bodies occupy. It is related to approaches on fields like psychology and linguistics which emphasize such embodiment such as cognitive linguistics.
In practice, this lets you account for details such as the available referents of indexing expressions. Definite articles in particular require unambiguous referents in technical writing. If you can rest assured that there is only one tool of a given type carried by users, for example, you can refer to that tool as the tool of its type such as ‘the hammer’.
You can also account for negative affordances that incur risks of failure given the user’s expected capabilities. If you expect that users will regularly be compromised in specific ways such as them having to split their attention, you can account for them in your technical writing. Such accommodations are unlikely to specifically address the effects of context-sensitivity in relation to reuse of content. However, it is best to generalize any solutions to such risks to make content more uniform and thus more reusable.
Nardi (1992) goes through the basic principles of scenario-based analysis in service of design.
McGrenere and Ho (2000) as well as Scarantino (2003) provide more detailed explanations of the nature of affordances.
Glenberg and Robertson (2009) discuss the role that environmental affordances have in helping people index expressions to what they perceive or conceive. Meanwhile, Kaschak and Glenberg (2000) discuss how affordances direct the interpretation of unfamiliar verbs.
Nomification
The term ‘nomification’ refers to providing entities with proper names. In the context of technical writing, such actions primarily involve providing parts with identifiers. For example, a galvanized medium phillips head screw with a length of 35 millimetres could be given the identifier ‘MPS35-G’. The first three letters provide its basic specifications, the number is its length, and the final letter specifies a variant.
Nomifications reduces context-sensitivity because it provides an invariant means to refer to the same type of object or procedure. Because proper names are implicitly definite, they can be used to avoid indexical expressions such as definite articles (‘the’). Proper names can also codify otherwise context-sensitive expressions such as adjectives that express relative properties. Such terms include ‘large’, ‘slow’, or ‘high’. In this respect, nomification is mostly used to complement explicit specifications (see above). Such specifications are simply applied to the established proper names for types instead of natural language expressions.
Good practice for naming components and procedures makes the names as evocative of what they denote as possible. The referent need not be obvious to everyone but it should require no referencing by the intended users of the documents. Some considerations in this respect involve (1) the ordering of information, (2) the parsing of information, (3) distinctness, and (4) relatedness. Not all principles apply (equally) to all cases and the list is not exhaustive but they provide an outline for coded identifiers in particular.
The ordering of information covers both priority and relations between expressed details. It is more important to make the type of component as evident as possible to help users understand what the rest of an identifier refers to, for example. In terms of relations, ordering helps express the degree to which two pieces of information are related: it is more likely when they are made adjacent to each other.
The parsing of information involves adding structure to a name. The most obvious form of parsing involves separating symbols such as hyphens or periods which chunk the information in question. For example, you can differentiate between the basic specifications, the dimensions, and the variant information for a given component and separate these types of information from each other with hyphens. The basic principle at play is no different from the separation of day, month, and year in date formats. When this support is not provided for them, users must parse said information themselves from the string provided for them. Of course, an explanation of the associated format should be made available to users somewhere in the documentation.
Distinctness refers to how different the names that you use are from each other. It is very important that names are not so similar that users risk mixing their targets. At the very least, there should always be a difference larger than just a single letter, especially for parts other than the first letter of a name.
Finally, relatedness consists of the extent to which the nature of the target for the name can be inferred from the name itself. Acronyms are often bad in this respect because of how abstract they are. However, if you use two letter combinations for some key words, they can clarify the referents considerably.
Let us consider these four factors in relation to the example of ‘MPS35-G’ for ’35mm galvanized medium phillips head screw’ that was provided above. Its ordering should start with the mention that the target is a screw. The name contains parsing but if ‘PS’ (phillips screw) is separated from the rest, the two letters become easier to understand. The user need not then recognize that the type of component is expressed by these specific letters. It appears hard to affect both distinctness and relatedness individually. However, when the information is parsed properly, users will know where to focus for the information that they need. Additionally, if the size of the required screwdriver is also provided instead of the generic term ‘medium’, it helps identify the correct item more easily. With these considerations in mind, a better name would likely be ‘PS-D2L35-G’. It denotes ‘phillips screw, driver #2, length 35(mm), galvanized’.
Mack (2012) addresses the proper use of acronyms in scientific writing. His tips ought to partly applicable in the context of technical writing as well.
Ahmad (2000) discusses the different types of nonces and neologisms used in science and the factors that lead to their more widespread adoption. These considerations can potentially help design more effective names.
Summary
Surrounding text is part of the context for any given piece of writing. Structured authoring involves the reuse of the same content in different positions. Thus, the same content will possess varying contexts. If that content is subject to contextual effects on meaning, not accounting for this variation can incur problematic patterns of misinterpretation. The extent and relevance of this risk is currently only subject to speculation. However, there are still means by which it can be minimized.
Different theories of meaning posit different levels of contextual effects. According to contextualists such as proponents of the relevance theory of meaning, such effects are pervasive and penetrating. According to them, context must thus always be taken into consideration when you specify the meaning of an utterance. Meanwhile, invariantists such as proponents of minimal semantics allege that there exists an invariant baseline meaning derived solely from the words used. If this is the case, then contextual effects are limited to indexing expressions such as pronouns (e.g. ‘it’) and modulation of this baseline meaning under specific conditions (e.g. use of irony).
The methods proposed here presuppose contextualism as a working hypothesis. If contextualism is true, then one must account for the risks that this would incur. If invariantism is true, then such additional effort may prove redundant but it is otherwise harmless. Moreover, these methods seek to locally control the contexts of the content to make them invariant enough to standardize related contextual effects across documents. In effect, this ought to reproduce conditions similar to those posited by invariantism. The remaining contextual effects such as proper indexing can then be addressed separately.
The proposed methods include (1) the use of controlled natural languages based on either external or internally specified standards, (2) the use of explicit specifications for details such as required amounts of torque, (3) use scenario analyses to identify available referents for indexing expressions, for example, and (4) providing proper names to the involved elements such as identifiers for specific types of components. Further considerations apply to each methods, such as how naming schemes ought to account for (1) the ordering of information, (2) the parsing of information, (3) sufficient distinctness, and (4) recognizably expressing some relation to the intended target(s).