Internal documentation in DoX and on DoX

I discussed how to research how your predecessors used DoX CMS if they left no internal documentation behind in an earlier piece. As I stated there, internal documentation on the conventions at play is essential. This is the case with all tools for structured authoring. This time, I will share considerations related to internal documentation for DoX CMS.

Internal documentation includes both directions provided within the system and any style guides with related instuctions. I will start with the methods inside DoX CMS for how you can record what to do. I will then discuss what an internal style guide must address.

Internal documentation in DoX

In DoX CMS, there are three methods for how you can document conventions and other details: names, descriptions, and comments. Each of them involves several available implementations within the system.

Names

The names of different components can express their functions. A name can only help users infer the proper application. Thus, names alone are not enough. Not all components can be given names with this purpose in mind, either. For example, the titles for topics are used in publications. The titles for publications inside the system can also be included in them like this. The system variable {{PublicationName}} retrieves this value and places it in content.

However, you can use names for internal documentation with these components:

• Folders for topics,
• Topic trees,
• Tags and tag categories,
• Variables,
• Attachments and their folders,
• Element classes,
• Styles and style sheets, and
• Workflow states.

Well-formed names provide hints on proper use and help filter views. However, you must also account for several other details.

Use English for the names of components. Later writers may not speak other languages such as Finnish. If a part of your material is in Finnish, they will not remember what to do without consulting available guidelines. This makes them fully reliant on such instructions.

When you specify names for variables, their alphabetical order makes a difference. All variables show in alphabetical order on the list in the text editor (after the next update). Additionally, publishing variables also show in alphabetical order in the menu where you can edit their values in a given publication. Thus, if specific publishing variables are strongly related and must be shown in sequence, you can add identifiers such as ‘aaa_’ before the rest of their names. These identifiers at the start help you control the order of publishing variables. Such identifiers should be formulated to account for the possibility that you must add other publishing variables between previous ones later. Include the details on what these identifiers do and how to determine their values in internal guides.

Descriptions

Descriptions let you add more detailed information on how to use a component. You can also include keywords and other identifiers inside them. These help you find specific components when you filter views. This functionality requires that the description for the component shows in one of the columns of a list view.

DoX CMS lets you add descriptions to these types of components:

• Revisions of publications,
• Topics,
• Styles,
• Values for complex variables,
• Translation projects,
• Styles,
• Element classes, and
• Transitions in the workflow.

Such descriptions other than those for the values in complex variables have corresponding columns in related list views. The descriptions for element classes also show on the list of element classes in the text editor.

Descriptions of publications’ revisions

Use the descriptions of publications’ revisions to describe differences to previous revisions, for example. You can also mention details such as the customers for unique deliveries or other distinct identifiers. If the descriptions of publications’ revisions include keywords to help find them with filters, you can add the keywords at the ends of their descriptions in addition to other information.

Topic descriptions

Use topic descriptions to describe where they are used. Like with the descriptions of publications’ revisions, you can use such descriptions alongside keywords. You can also include keywords like this: ‘Use this as a #template for #userManual #intro. Update the variables with new products.’ For grammatical reasons, English also works best for this compared to languages like Finnish. I added a number mark (#) before keywords in this example to enable keywords such as ‘#userManual’ as filtering conditions. The rest of these descriptions cannot accidentally include this exact string.

Descriptions of values for complex variables

You can specify descriptions for the values of complex variables in each language. Mainly use this option with their primary language. Use this description to tell where and how the variable is to be used. You can, for example, tell if the variable is only used as part of a cover or inside a different variable. You can also use this description for instructions on how to update the variable’s value. For example, a variable with the model name is usually updated thus: add a new phrase element inside it, write the name of the new model inside this element, and add the corresponding tag from the same category as the tags on other parts of the variable.

Descriptions of styles

You can specify the correct applications for styles, too, in their descriptions. It is especially important to do so with styles because the majority of users cannot themselves read the HTML and CSS files involved to interpret how to use them. Important details include suitable file types for deliveries in the style and differences between it and your default style.

Descriptions of element classes

The descriptions of element classes should tell about the associated changes in style. They should also specify the types of elements on which the element classes are to be used. The rules for them in style sheets generally only apply when they are applied to specific types of elements such as the frames for full tables rather than the table elements themselves. You cannot directly change the descriptions of existing element classes. You must remove the original element class and add a new element class with the same name and a new description, instead.

Descriptions of transitions in the workflow

When you make changes to workflow states, you can add descriptions to all available transitions to tell when those transitions should be used. Use the Action fields associated with each available transition for this. Even though this information does not show elsewhere, it helps new users know how to use your workflow. It is especially important to do this when your workflow includes changes, new states, or branching.

Comments

Comments are more situational than descriptions. They generally explain some situational change or choice to make some documentation on them available.

DoX CMS has these types of comments:

• Revision comments,
• Inline comments,
• Review comments,
• Comments in style sheets,
• Workflow comments, and
• Translation comments.

Revision comments

Revision comments let you write about the changes involved with each revision of a topic. This helps track the revision history of your content and use specific older revisions as the new baselines if specific details are changed back. If revision comments use standardized wordings, they also let you filter the Editor view based on the revision comments on the active revisions of topics.

Inline comments

You can use the text editor to add comments that only show in the editor (or in publications that use an appropriate style sheet) to specific elements. These comments let you explain idiosyncratric or exact conventions. They can also highlight less than obvious details in the text editor such as which parts involve content references (conref).

Review comments

The comments that you add during review show in the Comments field of the text editor. You can also add them in the text editor without involving the review function. These comments let you deliver requests to change details based on your review of the content. Yoiu can also use them for other information related to a revision if that information is not suitable for a revision comment or an inline comment.

Comments in style sheets

CSS lets you add comments between the identifiers ‘/*’ and ‘*/’. These comments let you add parts that do not change how they work to style sheets. You can use such comments to add structure to style sheets, to clarify selectors’ targets, to explain what element classes or specific rules do, and so forth. They also let you add references for details such as recurring color codes, if the compiler does not let you use CSS variables for this.

Workflow comments

When you move content from one workflow state to another, you can add a comment. This comment will be a part of the email message sent to the selected user. All these workflow comments also show in the Revision Details menu in relation to those reservations, though. This lets you document observations related to the content’s workflow. Such observations can later help resolve why a specific error remains in an approved revision, for example.

Translation comments

The system does not record translation comments. They are only a part of the email message that it sends to the selected user. If you keep an archive of those emaill messages, you can use these messages to also track how the system is used. This is especially useful if errors or other unexpected behaviour occur in relation to translations.

Internal documentation on DoX

The methods to keep notes inside DoX CMS that were discussed above are insufficient for all the documentation on conventions that structured authoring requires. You also need a separate internal style guide which details the presuppositions involved in how prior content was formulated.

Below, I will discuss details related to DoX CMS on which you should maintain internal documentation.

Language use

Rules on language use include the principles that control how sentences are formulated. Such practices are not unique to structured authoring. A uniform style requires instructions on details such as grammar and approved words.

Sentences

Sentence level instructions relate to details such as sentence length and grammar. For example, the eighth edition of ASD-STE100 lets you write instructive sentences that are 20 words long and descriptive sentences that are 25 words long. If you use such rules, you must record them.

Grammatical details of note include these, for example:

• Passives: If the use of passive voice is not forbidden, you must list the contexts in which its use is allowed.
• Person: You can sometimes replace passive voice with the use of specific pronouns to address audiences. For example, you can use the second person plural pronoun (‘we’) for your company. Write such conventions and their proper applications down.
• Tense: It is often best to only allow simple tenses. Tell your users which tenses they can use.
• Conjunctions: You should use conjunctions. However, you should also specify which of them are allowed and which can be used to start new sentences.
• Derivatives: You should limit the use of derivative terms such as deverbal nouns. Write down any rules related to this.

Dictionary

Your dictionary defines approved, disallowed, and recommended words for different situations. Everyone should write a dictionary for keywords and abbreviations related to their own products. You can also include a more comprehensive list of approved words such as the dictionary from ASD-STE100 or an adaptation of it.

A list of the keywords and abbreviations related to a product lets you specify the exact spelling. Keywords need not be unique to your products even if many of them will undoubtedly be. They also include the terminology for referring tyo parts of your products such as the distinction between ‘dock’ and ‘connection point’. It is especially important to define the spelling for central compound words: when should use hyphens or spaces and when you should write the words together. The simplest solution is to document the correct spellings and when each must be used.

Another important part of a style guide is a disctionary of approved words such as the verbs for different actions. Ideally, this dictionary will also include disallowed words alongside the situationally appropriate approved alternatives. Also record the approved meanings for each word and altarnative words for their other meanings. For example, the word ‘select’ can carry too many meanings. If this is the case, you can specify ‘highlight’ as the approved word for selecting parts of text, for example.

Editor conventions

There are details other than language use that you must account for in relation to the text editor. There are often rules for details such as which elements must be used at the start or the end of a topic. How you may use images together with lists can also involve different rules. For example, only some images may be allowed within lists. You can also have lists continue in a way that lets you add images between parts of them.

Here are some details to account for when you use the text editor:

• Order of content: Style sheets and predicted page layouts in particular affect the order in which you must use different types of content. If the style sheet contains rules such as that lists must start on the same page as a paragraph before them, you must use such a paragraph before all lists. Rules for page layout, on the other hand, determine which parts start on a new page and which pages will contain large elements. Document such conventions in your style guide.
• Sections: You can use section elements to structure the contents in topics. They are only really useful when they are used more widely. This lets you use them for content references (conref), for example. If sections must be used anywhere, mention this in your style guide.
• Metadata: If you use the prolog field and the data elements in it, record which values for them each topic must have. If some such elements are embedded, also describe the relations between them.
• DITA attributes: The DITA attributes of each type of element let you control details related to those elements such as how text aligns inside tables. It is generally best to control such details with style sheets, often with the help of element classes. If your documentation uses DITA attributes, though, you must mention it in your style guide to continue such conventions.
• Conrefs and variables: You can have single-sourced parts inside topics with the help of content references (conref) and variables. This involves individual source versions which control the content of repeated target versions. Users must know when and which pieces of single-sourced content they must use to properly utilize these systems.
• Conditioning: How tags are used properly is not obvious. You should write down instructions on this: which parts are differently conditioned alternatives, are there variables with conditioned content, and so on. If you condition different parts differently, parts of content may look different as a result. Such errors can also lead to unnecessarily copied content which is no longer single-sourced as a result.
• Use of element classes: The na,es and descriptions of element classes often cannot fully describe how you must use them. Especially when element classes are an essential part of writing your content, you should also discuss how to use them in your style guide.

Descriptions of style sheets

Most users cannot read or write CSS and they cannot be expected to do either. As such, you must record any details in the style sheet that affect the writing process in your style guide. Some examples were mentioned above, such as paragraphs before lists if the two are forced on the same page. You should also write lists on rules related to these kinds of details, for example:

• Covers: You can do covers in a variety of ways. They are often highly reliant on style sheets for the layout of the different parts and a standardized background, though. Clarify such details in your style guide to allow other users to make changes to the covers. Some implementations also require them to know how they must add new covers.
• Page headers and footers: You must sometimes change details inside page headers and footers. To do so, users must know how the values for these parts are specified.
• Page breaks: The rules that control page breaks can often confuse users. Make things easier for them with a list of rules related to the positions of added and disallowed page breaks. Also explain why these rules exist. This prevents other users who are ignorant of the rationales for these general principles from changing them to improve layouts for individual positions.
• Element classes: Even when element classes are addressed elsewhere, you should repeat the rules related to each when you describe style sheets. You can make this part descriptive rather than instructional.
• Titles: Describe the styles for the titles at different levels of organization. For example, if the field for number identifiers has a uniform width, record such details. This lets other users account for how much space is available for them when they compile topic trees. If you use the shortdesc field for some or all topics, also mention this detail.
• Note elements: To translate the titles for note elements, users must often make changes to style sheets. This makes information on them important. Tell which types involve specific rules and whether further actions such as the use of element classes that change the icon to match the type of danger (e.g. electric shock) are also necessary.
• Tables: Tables are the most complex type of element. If rules related to them in the style sheet are ignored when you write content, their layout can break as a result. For example, different horizontal paddings between columns or alternating backgrounds for rows or columns are incompatible with split and merged cells.
• Images: If image sizes are controlled with the style sheet, share the principles and rules related to this with users. This lets them adjust image sizes. This also helps avoid situations where they use the text editor to unnecessarily add values to individual images. It is a challenge to update values for individual images across languages.
• Lists: Descriptions of lists should tell users how embedded lists work and when they are to be used. If you use custom numbering which only resets list numbers between topics, for example, you must tell other users about this in your style guide.

Workflow

You should mostly describe the workflow when yours includes changes relative to the default workflow. Such changes include new states and different allowed transitions, for example. Ideally, show your internal workflow as a flow chart. Otherwise, a list of the different workflow states and the available transitions related to each, for example, is also viable. This makes it clear to users how they should handle the content outside the text editor. The workflow is also connected to other features such as reviews and translations.

Translation conventions

There can be different conventions for handling translations, too. You should record your conventions related to them. Such conventions include the likes of these:

• Prepare the originals: Record everything that you must do in the original language before you start a translation project. Usually, this requires that you approve both the publication and its topics through the workflow first. This minimizes the need to correct errors other than those made by the translators. Tags are also applied to content in other languages with the help of translation requests. Make sure that all conditioning is finished for the time being first.
• Send the translation request: You can have different conventions for translation requests as well. For example, translations of publications should use the same conventions as before in relation to whether you lock the revisions in the target language. Otherwise, the publication in that language can inherit the wrong locked revisions and continue using them.
• Standardized foreign expressions: If translations in other languages must use specific expressions for your technical terminology, for example, document those expressions. This lets you convey them to the translators.
• Translations outside translation files: Not all content to be translated is compatible with translation files. Translation files only contain the main content and the values for selected variables. If you use images that must be translated or style sheets to add details such as titles for note elements, tell users in your internal documentation how they must translate them and then deploy the translations.
• Manage translated content: The revisions of the same content in different languages are managed independently. For example, if you must change the addresses for image elements to target translated images, you must do this separately in each language. You can avoid the associated risks and labour if you anticipate such needs before you send the content to be translated. You can easily manage translated images in the menu for attachments when you target localized images with image elements. You can also use element classes, for example, to control details that otherwise require using the text editor such as image size across all languages.
• Upload translations: Even when you upload translations to your system, you must account for details such as who uploads the content and how you will handle a different person doing it. Document the correct conventions and the reasons for them for future users to apply.

Summary

Maintain as comprehensive internal documentation on the correct conventions for how to use your copy of DoX CMS alongside the content within it. This makes information on these conventions available when your users change. The risks involved with changes in users are reduced greatly when new users need not infer or guess how they should use the system. Tools for structured authoring require uniform conventions to maintain the quality of the documentation and to benefit from the features of such tools.

Within a system, such documentation consists of names which clearly express intended uses, descriptions that clarify proper use, and comments with further information. They can guide users and remind them of situationally appropriate ways to use the system. However, such instructions are insufficient. You also need a separate internal style guide.

This separate internal style guide must account both for available forms of language use and the correct conventions in different contexts. The instructions related to language use involve sentence level details such as grammatical limitations and a dictionary. The dictionary must include at least keywords and technical expressions. It can also include a more comprehensive list of both allowed and disallowed expressions for different situations. Conventions concern how to use the editor, style sheets, workflow, and translations, for example. They help ensure that both content and how things are done remain uniform within the system. Like this, the variety of interacting systems remains coordinated in a way which maintains their ability to produce the expected results when you compile publications.