When I attended the 2022 Vakki symposium, I discussed the means to increase how usable documents are with the presenters after one of the presentations there. Specifically, the topic was how to target content batter according to users’ needs and how dois so is all too often based on assumptions by people other than these users about the suitable levels of expertise. In this piece, I will discuss my thoughts since then on how DoX CMS could be used to address such challenges.
The basic concept is that HTML publications, for example, still contain the identifiers used to condition content and that filtering content on this basis can also be done afterwards based on a user’s choices. I will also throw around some varyingly realistically examples of possible filtering conditions for such purposes below.
User-Controlled Conditioning
The basic principle for conditioning content involves specific contents being associated with identifiers which let you either include or exclude these contents when you compile publications.
In DoX CMS, such conditioning involves the use of tags. Tags can be applied to either topics or the elements therein. Each tag belongs to some category. For the thus identified contents to show in a publication, that publication must itself use at least one corresponding tag from each tag category from which the content has tags. For example, if the content has been specified to be used in the user manuals for a set of models but not in their maintenance manuals, the manual must be identified with one of these models and as a user manual. Only fulfilling one condition is not enough.
At least in DoX CMS, conditioned content retains its identifiers after it is published. This allows filtering to be done after the content has been published. This empowers users to set the conditions for doing so. Implementing such an arrangement involves three factors that are listed below.
Unfiltered Publications
As was stated above, the identifiers used to elements retain the identifiers that are used to condition content through the publishing process.
As such, publications which contain all such conditioned content also allow that content to be managed later based on these identifiers.
In practice, such publications require that you select each identifier used to condition content when you publish them. When you do this, no conditioned content is filtered out. Instead, all such content is included in such publications.
Interactive Publishing Format
An unfiltered publication by itself is unusable, especially if the conditioned content in it includes images and/or consecutive phrase elements (ph).
Thus, if you cannot affect which content shows afterwards, this method is useless.
HTML is one example of a publishing format where the background structure is retained and which can be managed actively as a result.
PDF, on the other hand, is an example of a publishing format where such active management would prove… challenging.
Menu That Controls Visibility
Once all the required content is available and the publication can be managed actively, all that is still required is a means for users to control said contents.
Doing so requires a menu which lets users control which contents they see. Some possible sets of values to control are discussed in more detail below. Depending on the details of how content is conditioned, such a menu can include either stepped slider or multiple choice selection fields, for example. For eample, a slider can be used to raise the complexity of content and multiple choice selection fields let you list relevant circumstances.
The simplest method that I can think of to reflect the choices of individual users is based on controlling a stylesheet saved in the user’s cache by adding (or removing) rules that hide content with specific identifiers. Similar functionality ought to be possible to implement directly with Javascript, too.
In terms of the CSS in the stylesheet, this is what the rules to add or remove would look like:
[data-doxattribute-categoryID="tagID"] {
display: none;
}In here, ‘categoryID’ refers to the identifier for the tag category and ‘tagID’ to the identifier of a specific tag in it.
This kind of menu could easily be incorporated into the virtual or enriched environments where content is maintained with the help of VAD, too.
Forms of Conditioning for Users to Control
Once conditioned content can be shown or hidden after it has been published, you can also apply forms of conditioning which differ from those used for static publications. Some available grounds for conditioning content like this are presented below.
Subject-Specific Conditioning
In this case, the user can decide the subjects for which related content is shown to them. Such subjects can include the likes of the the type of manual in question, such as ‘user manual’ or ‘maintenance manual’, or features of a piece of software such as ‘user management’.
If content related to multiple types of manuals can be shown in parallel in this way, the related instructions need only be separated from each other through conditioning. The manual being used can be kept properly focused based on the settings that the user selects.
Centrality
Centrality refers to the expected utilization rate for a piece of information. The more central a piece of information is, the more likely it is that it will need to be accessed (frequently). For example, instructions related to how a machine is turned on are (generally) more central than instructtions related to how user-specific settings for that machine are controlled.
This value can be specified separately for each subject. When you do this, each subject acts as a category within which there are several available levels of centrality. For example, it would be possible to let the user specify in relation to user management whether they are shown only the core information, only further information, or both. The details depend on how this is implemented.
Complexity
Complexity consists of the density of information and the challenge involved in absorbing it. The more information there is in relation to a subject and the more cognitive resources it takes for the user to process that information, the more functionally complex that information can be treated as. Processes with more steps are more complex than those with fewer steps, unless each step is relatively easier to comprehend.
Like centrality, complexity can be specified as a subject-specific variable. Such subject-specific variables can each be organized under these subjects. If you wanted to differentiate between (1) simple core content, (2) complex core content, (3) simple further content, and (4) complex further content in relation to the parts acting as a user manual, it would take identifiers from three categories. You would be using only one identifier from each in relation to both centrality and complexity on each affected piece of content. If, for example, you want to also show simple contents whenever complex contents are shown, it does not require the use of both identifiers on the same content. Instead, when the option to show complex content is in use, you can elect not to hide content with either identifier.
Language Variants
Generally, there is insufficient reason to maintain more than one version of the same content per language and this version will be the one that suits most users. In principle, however, such variants can be written separately and conditioned accordingly. One real example of this being done is the difference between American English and British English.
Is there ever a reason to let the user choose between American English and British English? If the content has not been translated to the native languages of all international users, English is the default for what they will use instead. International users are provided with the content in American English by default. In the case of individual users, though, it is perfectly reasonable that some might prefer British English. If both versions of the content already exist, there ought to be no reason to bar international users from using the variant of English that they prefer.
Circumstances
A more interesting form of conditioning for users to control consists of both personal and situational circumstances. Usually, manuals would at most account for the most relevant such conditions to avoid an overabundance of circumstantially useful content. When users can control the visibility of such content themselves, they can include all the parts that suit them and only those parts.
Personal circumstances include the likes of hair length, wearing glasses, and allergies. Each such condition can incur additional steps or warning such as ‘cover your hair and make sure that it cannot be caught in the saw’. Usually, only the most dangerous or common such conditions would be accounted for. When all of them which are not personally relevant can be filtered out, it is possible to account for more types of personal circumstances and to include mentions of them in the main content, such as in additional steps for procedures.
Situational circumstances include, for example, the weather. It can then be divided into several factors such as the temperature and rain conditions. Under particularly cold or hot conditions or while driving in mud and so on, precautions ought to be taken in response to these circumstances.
Roles
Users in different positions can have different needs based on the tasks allotted to them. Different roles can also involve different permissions or duties which can be used for as a basis for conditioning as well. One form of such permissions are different driving licenses. In terms of duties, a driver might need basic maintenance or repair instructions in addition to operating instructions and a mechanic might need enough operating instructions to run tests.
Needs
Since users can control the visibility of content based on their situation, they can also use conditioning as a form of content search. When users only need portions of the manual related to specific features or operations, they could filter out all other content and search for answers without needing to browse through unrelated sections.
A need can be specified, for example, based on an issue: if the machine does not turn on, you will only be shown the possible procedures to address this. In such situations, it is often important to find answers and means to proceed as quickly as possible. A need can also be specified in an anticipatory manner by, for example, conditioning maintenance procedures based on utilization rate or years of operation: after 100 000 travelled kilometers, you must check the transmission cables for wear, and so on.
Previews
In principle, it would also be possible to grant users access to content related to features or other kinds of updates which are not yet a part of the product. This option primarily affects software and other products actively maintained by their provider.
Enabling such previews by including unfinished content to delivered manuals and by conditioning its visibility to be controlled by users lets users get acquainted with these contents in advance. When this option is provided to them, they can learn about new features before they are implemented instead of only doing so after these changes occur. This makes adopting these features happen faster. If users are provided with a related feedback channel, it can also help you account for challenges and needs which are evident from their perspective before the final version is delivered.
Other Considerations
Besides minimal conditions and potential applications, user-controlled conditioning also involves several other considerations to account for. Extending similar operations to styling and means to ensure that the content layout works correctly for content that is managed like this are discussed below.
Controlling Styling
You can allow users to control not only content visibility but also how pieces of content are styled. For example, you can make changing fonts to be dyslexia-friendly be implemented similarly to how content visibility was suggested to be controlled above. Increasing image contrest, too, as one way to help people with different forms of color blindness can be done in the same vein.
Controlling styling can also be linked to identifiers in the same way as conditioning content visibility. In DoX CMS, this involves the use of element classes. They let you, for example, denote keywords or other parts that users can highlight as needed to increase how distinct they appear. One example of this would be a temporary setting which makes parts of step lists other than whichever is active or below the cursor fade out. Doing so lets users ensure that they do not accidentally read instructions related to the wrong step when they double check what they should do.
Since this is not the main subject of this piece, I will not go to more detail about the possible means of implementing such features.
Proper Layout
When users can control the visibility of content, there will almost inevitably be more possible combinations of shown content than otherwise. If the relationship between consecutive sections of content is not controlled carefully, the user can accidentally break how text is composed. This risk is especially noteworthy in relation to elements inside text blocks such as phrase elements (ph) and images.
The simplest solution to this is only conditioning possible sources of such issues in relation to one category at a time such as the units being used. If the user can still simultaneously show contents related to more than one identifier within one category, though, you must add connecting material between associated parts. Such material cannot be a part of the main conditioned content if the latter can also be shown independently.
One solution to this would be to use separately conditioned elements for this connecting material that can include slashes (/) or the word ‘or’, for example. In this case, they can, for example, be marked with the identifiers for the parts on both sides of them and with identifiers from a separate category which specifies the primary category to which they relate. Doing so lets the connecting material marked as being related to a specific category and with specific identifiers from that category to be shown when those identifiers are used simultaneously.
For units, for example, it is possible to show both the amount of pounds and the amount of kilograms in parallel. A slash symbol (/) can be added between these values to separate them. In this case, the relevant sections would each consist if three phrase elements (ph): 1. the amount of pounds, 2. the slash symbol (/), and 3. the amount of kilograms. Both elements that express an amount would be marked with an appropriate identifier related to the unit in question. The element for the slash symbol (/), on the other hand, would have an identifier that expresses that it is a connecting part related to weight units, and the identifiers for both weight units. If there was a third unit being deployed, the elements with slash symbols (/) that separate it from the alternatives would have similar identifiers based on the units used around each of them. In this case, the system would be told to show these separators between other elements when more than one related identifier is selected but only when each of the identifiers applied to them from these categories is deployed.
It is worth noting that such filtering does not comply with how contents are filtered based on their tags in DoX CMS. This method cannot thus be used with traditional publications published through DoX CMS even though applicable content can be written in DoX CMS and it would be compatible with later filtering in this way. The reason is how filtering when content is published never requires the use of more than one tag from the same tag category. If even one tag from a category in use is selected and other conditions are also fulfilled, the content conditioned like this will be included in the publication being compiled.
The implementation of this solution should also be developed to account for situations where one or more sections are skipped because (only) they are filtered out from a publication. Unfortunately, I have yet to discover a means to ensure that the content layout functions properly in all such instances. A further option might also involve the stylesheet in the form of an instruction which adds the connecting pieces after every section in a sequence save for the last as a ‘::after’ pseudo-element.
Summary
When content that was published unfiltered in a suitable format is deployed as part of a system that lets you control the visibility of content based on the identifiers used to condition it, users can be provided witht the power to control what content is visible to them.
When this is the case, the writer has to worry less about what contents are appropriate to include in each manual. They only need to account for how challenging or relevant each piece of content conditioned like this is. Users can themselves determine the subjects where the basics suffice for them and when they ought to also see the less central or more challenging content.
This also allows new dimensions along which content can be conditioned such as various circumstances or a need-to-know basis. When maintenance is performed with glasses on during a wintry night, this situation can have further associated instructions that can be delivered to the user without filling a general manual with otherwise irrelevant, situational observations.
Similar levels of control can also be expanded to styling content based on users’ needs. For example, when users are actively referring to a manual instead of browsing through it, they can benefit from the ability to fade out steps in a procedure other than whichever is relevant at the time.
When you are going to show consecutive pieces of content, you will need separating sections which must be conditioned separately. This will make them show only when several values are listed in sequence, Doing so can involve the use of a distinct category of identifiers that is used to determine the values to which such connecting sections are related. When these contents are marked with such identifiers alongside the identifiers for the values around them, they can be shown only alongside the parts with those values.