It is too often that I come across situations where the only technical writer in a company has changed and the new user was provided with zero internal documentation on how to use their copy of DoX CMS. Maintain internal documentation on such things. No one wants to be put in this situation. DoX CMS is a flexible system that consists of multiple general features that can be combined in different ways, after all. This can leave a new user with no idea of how they have been applied. When this happens, it can easily result in errors which will take an inordinate amount of time and effort to fix.
If such instructions are not available, though, this piece will discuss the details that new users must account for when they start to use a DoX CMS environment inherited from prior users. If one is requested, we will also provide all new users a brief introduction to DoX CMS and also further meetings at our hourly rate to teach the user more about the system.
Identifiers
You should first get a general idea of the environment in question by checking the identifiers and other forms of differentiation used therein. It helps to show the associated columns such as the comments on topics and their revisions. Which tags from which categories also reveal much about the distinctions at play.
Comments
DoX CMS lets you add comments to topics, revisions for topics, and revisions for publications. Such comments let you add freeform metadata based on which list views can be filtered to find specific items. As such, many environments use standardized identifiers and keywords in them. When you enter an environment built by others, you should start by checking what kinds of identifiers (if any) have been used like this. If such identifiers are found, show the related columns in those list views.
Further information on how to filter list views is available here.
Tags
It is very important for new users to understand how prior users have used the distinctions related to tags. This is discussed further in relation to conditioned content. However, you should learn as soon as possible which details have associated tags and how they have been categorized when you enter an old environment.
The primary categories for tags are based on tags on level 1 of their hierarchy. There can also be subcategories inside these primary categories. Thus, examine which details involve the primary tag categories and whether subcategories are involved.
Also check if there are tag categories which are unrelated to filtering content for publications and instead have a less clear application. For example, environments that were established before topic trees were introduced (and the S version) can involve tags to remove topics from all publications. This is a result of some publications having used the master topic tree in the Editor menu as the baseline from which content is filtered.
Your goal should be to investigate which tags are used together when you condition content and when you publish content, respectively. Once you have a working theory based on the categorization scheme and the contents of categories, you can compare it to how tags are used on content and the tags selected for publications. This will also show if there are more exotic implementations that involve tags at play, such as designating incomplete parts with tags the specify which actions are still required. If this is the case, you should filter views to show such content to review it and to finish it.
Settings
The next thing to study are the settings that define wider proper conventions. This lets you know the framework within which the other parts of the environment were built to operate.
Settings menu
The Settings menu is used to define values for several operating principles which have a widespread effect on how the environment should be used. The most important setting there concerns whether topics with no tags are included in publications. It determines whether all content to be published must have tags. When you use properly specified topic trees, there is mostly no need to prevent topics with no tags from being included in publications. This setting interacts with a different setting: when topics with no tags are not included in publications, you generally also want to use the setting which adds the tags that you add to elements to their topics as well.
The Settings menu also controls when you can add new revisions to topics. They must either be added before you make changes to them, or you can make the changes in the editor first and then save them in a new revision. The second option is more intuitive but also more risky.
The Settings menu also shows the format for the titles added to (full) tables and figures. This format is also used for internal links that target those types of elements. If this value is empty, that environment involves some workaround which was deemed incompatible with such generated titles. My condolences. This means that the system has not been used as intended and this will limit the functionality of internal links in particular.
Workflow
A list of the used workflow states can be found in the Workflow States menu under the Tools icon. Examining this list can reveal what additional states the environment expects you to use and which transitions it allows.
The available transitions are shown on the rows for each state in the Possible Next State(s) column. This lets you chart the available routes from adding new content (the Normal state) to approving it (usually the Approved state). It is also a good idea to check the settings for the Approved state and any added states. The Edit Workflow State menu can also be used to specify what roles users must have to reserve content in a given state. When no role is selected, that state is used to lock content for purposes of approval or archiving, for example.
Publications
Publications pull together all the prepared content. Their settings thus tell you how said content should ultimately be used.
The Edit Publication menu lets you check the settings of each publication. It shows, for example, which styles, cover pages, and topic trees each publication involves. It also shows how the various publishing variables are used and which of them have language-specific values. The values of publishing variables with language-specific values are preceded by the identifier for the active language. The Revision column on the list of content shows whether publications involve the use of specific revisions or whether they will automatically update to use the default revision. The Tags tab, on the other hand, shows which tags are used to filter the contents for a given publication.
Components
Topics are the main components from which structured content in DoX CMS is compiled. However, they will be addressed separately in relation to formatting. In addition to topics, DoX CMS contains variables and content references, for example, to let you make changes to repeated pieces of content all at once. Users should also be somewhat familiar with the styles that they use even if they do not know how to make changes to them. They often tell you how different types of elements were expected to be used.
Variables
Variables are repeated pieces of inline content such as icons, contact details, or the names of models. They allow for surprisingly complex implementations which may contain embedded variables, conditioned values, element classes, and so on. This is why you should examine variables closely if the environment in question involves their use. Variables are found in the Variables menu under the Tools icon.
There are three types of variables: (1) basic variables, (2) complex variables, and (3) publishing variables. The values for publishing variables were discussed above. Note how they might not be used in content directly. They can be included in other variables or page headers or footers instead. Basic variables only have one value whereas complex variables have language-specific values. Open these variables in the editor for the Variables menu and take notes on how the values for different variables are constructed. Pay special attention to tags, element classes, and other variables. The positions where variables are used involve the names of those variables inside two sets of curly brackets ({}).
Then check which variables are used in content proper. The Variables menu has a command, which shows the revisions of topics which include the selected variables. Even if a variables is not used in any topic, it may be included inside another variable or a page header or footer.
Content references
Content references (conref) operate like variables. They let you use singular source elements to control the content of repeated pieces of content. Content references let the target elements that share the same content retrieve that content from such source elements. Since these elements were made to be reused, users must know the situations in which they are used.
You can find the target elements for content references if you use the Editor menu to find the content ‘conref’. Only these elements have a Conref value and this feature finds the content in the source files. When you use the browser’s find feature with the value ‘conref’ on the Source view for one of these topics, you will see the location of the source elements for the target elements that it contains. There is a numerical value between the # and / symbols for this value. Copy this value and paste it on the find field under the title of the Topic ID column in the Editor menu. Remove the prior filter from the content search with a new one which uses an empty find field. This will show the topic that contains the source element in question. Select it and remove all filters. There is a good chance that other source elements are contained in the same folder’s other topics.
Styles
Styles are not only applied when content is published to define its layout. As is discussed here, for example, each style also requires content to match the involved expectations. For example, large, continuous elements such as big pictures or tables may have to be added at the tail ends of topics. A style may also have a rule that always prevents page breaks before lists because lists are always assumed to be preceded by short paragraphs which describe the contents of those lists. Even if you should lack the expertise with CSS needed to manage a style sheet, you should browse through it to have a general sense of its contents.
You should pay special attention to the rules for element classes and language-specific values. Element classes were added to the system to address specific needs. Ideally, what they do is obvious based on their names, or this is described in the descriptions for said element classes. For this reason, it is especially important to understand what kinds of changes they involve before they are used (or left unused). You can identify the part(s) of a style sheet related to element class based on the identifier ‘doxelementclass’. You can also use the find feature on a style sheet to locate them.
Language-specific parts, on the other hand, will have the identifier ‘lang’. They almost invariably involve the rule ‘content’. You should find all parts of the style sheet which involve this command just in case. It is important to know the language-specific parts because they require new values when you add translations to a new language. Further information on this is available here.
Formatting
Once you have a general understanding of all the factors which affect how the main content is formatted, you can survey their formatting. You can also have a look beforehand because these arrangements interact both ways. You should form a proper sense of the formatting of the content because in the absence of an internal style guide, you must deduce the rules at play. You must get this part right.
Rules for writing
Structured authoring often involves implicit rules for writing such content to make compiling it more predictable. This makes an internal style guide an important part of ensuring uniformity. I will only address some of the details that require special attention when no such guide exists.
The first and most obvious detail to note is whether content is written in the Content field or the Sections field in the text editor. Usually, all content will only use one or the other. The Sections field requires a suitable style sheet but it provides further functionality such as content references (conref) and titles for the sections within. Use the same field as previous content. Also check when and how the Shortdesc field and Prolog field may have been used.
Analyze how and when the different types of tables have been used. Some situations may require simpletable elements. If tables apply different margins to different columns, you cannot use split cells in them. As such, you must be careful when you split cells. For the same reason, we recommend that you keep margins and similar details uniform across both columns and rows. Survey whether full tables (and figure elements) have titles or descriptions, and how they are formulated.
Check how and when lists use further indentation. You should also pay attention to details such as how lists use capitalization, punctuation, bolding, and so on. Like was pointed out above, you should also study whether all lists are preceded by some form of standardized description of their contents.
You should obviously also note the wordings, and element classes as well as image sizes and other DITA attributes. Media elements such as videos in particular require you to change DITA attributes instead of using their default values. There are several alternative implementations.
Conditioning
You must closely examine the ways in which tags are used to condition content. If they are used differently in different places, the results of filtering content will also be varied across documents.
The importance of proper conditioning is heightened by embedded elements. When inner elements are conditioned, the elements in which they were embedded will be unaffected by filtering. As such, you should elements of the highest available level as long as that level is suitable to present each of the required alternatives. This is not always necessary such as in the case of the paragraphs inside note elements in place of the note elements themselves. What matters most is that this system remains uniform. This applies especially to situations where several alternatives would be suitable.
Be very careful when this involves table cells on the same row. Such arrangements can include situations where a picture can be added or removed next to a piece of text. Such situations are more likely when transperent tables are used to add columns to content. If this is the case, in addition to studying how content is conditioned, you should also make sure that column widths are defined in a way which ensures that the used content has a suitable layout. In practice, any width values should only be defined for the parts that are conditioned. When they get filtered out, the other parts without such specifications divide the remaining space according to the default rule used for tables.
Manual
New users should also have a look at the user manual for DoX CMS. This will provide you with at least an overview of the system’s features and the related practices. The system contains some features that are not evident to new users such as how revisions that have been translated to a specific language are excluded from new translation requests to that language by default. Our training when the system is first deployed addresses such features. However, as was mentioned above, any training besides a basic introduction in old environments involves an hourly rate.
The manual tells more about both how to use the various features and what the different parts of the interface do. You should study the sections on how to use the system as well as the tables on best practices and frequently asked questions before you use the system. The parts about the different menus of the interface should be read at least when you use those menus for the first time. They will help you understand what each part of the menu does.
Of course, you can also contact our support. The email address for our suppor is available in the manual. You can also use the Contact Us command under the Tools icon.
Summary
When a new user arrives in an old environment with no guidance from prior users or an internal style guide, they must research how the system has been used by themselves. It is very inconsiderate to force anyone in this position. As such, it is important to document such practices.
You should start an investigation of an old environment with the identifiers related to its contents. These identifiers tell how this content is differentiated. This helps you continue with the same categorization scheme(s) and find the correct parts of content. The most important forms of such categorization are different kinds of comments and the available tags and their respective categories.
Next, you should seek a general understanding of the framework within which you will add and edit content. To this end, you should check the selected values for the settings in the Settings menu as well as the settings for the workflow and publications. The state of the workflow tells you how content is to be treated during each step of the writing process. The settings of publications, on the other hand, show which content is used in each of these final use sites and how.
After this, you should study the various kinds of components that are used when content is compiled into a publication. Before you have a look at topics, I recommend that you check the other kinds of components. Such components include the likes of variables, content references, and style sheets. When it comes to variables, you should examine which are used in content proper and which only in page headers or footers or as parts of other variables. You should also investigate whether they include tags which filter the contents of the variables when they are used in different publications. As for style sheets, you should get a general sense of their contents and study how language-specific parts and elements classes operate.
When the time comes to handle the main content and how it is formatted, you must analyze which kinds of rules the formatting involves and how this content is conditioned. This involves the kinds of fields (not) in use such as sections for content, as well as other formatting details such as where words are capitalized. Conditioning must be kept uniform across all content. Otherwise, the pieces which are conditioned differently within a publication will behave differently when this content is published.