Structured authoring alongside the systems that support it constitute a process with multiple steps. Despite how the details of this process can differ based on the needs of each enterprise, systems have their built-in default workflows. This default workflow provides a skeleton based on which any changes in the process are specified and which restricts the available implementations.
I will proceed through the details of the default workflow for DoX CMS below, alongside the reasons for them. A similar section will also be added at the start of the system’s manual.
The workflow as presented covers everything from deploying the system to content deliveries. I have divided it into seven primary phases, and the sub-systems and available implementations related to each are discussed separately.
Planning Phase
This is the most important stage. Planning helps organize the features of a system into a whole that serves specific needs. Insufficient planning when a system for structured authoring is deployed may cause it to remain underutilized or the need to redo content. When deployment is properly planned, though, new manuals can be compiled as easily as by specifying the values for several variables and selecting the appropriate tags.
Several examples of details that must be accounted for when DoX CMS is first deployed are provided below.
Roles and Permissions
The basic roles in DoX CMS are those of user and admin. Other commonly included roles include those of reviewer and translator. Besides these common roles, it is possible to specify other user roles with their own sets of associated permissions.
Planning roles involves deciding which users get admin permissions, how user profiles purely for review purposes are implemented and whether special roles will be needed.
Admins have almost complete administrative control. It can be tempting to grant all users these permissions but if they are applied carelessly, it can lead to a tug of war that hinders content production. For example, admins can forcefully reserve content already reserved to others users. If the more than one user is editing the same content simultaneously, though, only the version that was last saved between them will be retained.
It is possible to add user profiles for secondary users such as reviewers and translators and the associated login rights can be cycled as needed. Doing so requires management and how that is implemented ought to be planned together with the users.
Content Format
DoX CMS supports you writing the content in either LW-DITA or HTML format. It is also possible to include PDF content but it has limited functionality.
Each of these formats has its merits and flaws and they can be combined in various ways when needed. The default format, though, is LW-DITA which supports more features such as content references (conref) that lets reused elements be controlled through a single source element.
LW-DITA also has a wider selection of functionally differentiated elements such as distinct note elements for warnings and the like. Finally, the greater functionality of this format includes details such as separately defining whether individual elements ought to be translated and more options for titles.
When LW-DITA is used, you must decide whether the content will primarily be written in the Content field or the Sections field. The former is simpler to manage. However, the latter enables options such as content references for elements that do not otherwise support said feature of for sets of elements in sequence.
HTML has its own element types with no parallels in LW-DITA such as horizontal lines and its editor has commands such as Replace All. Additionally, tables in HTML contents are at least currently easier to manage.
Settings
DoX CMS lets users specify how some features operate from its settings. These settings affect all users in the shared system. They ought to be accounted for as part of the intended user experience.
One setting specifies whether untagged content modules are used in publications. When this setting is on, general content modules need no tags. When it is off, all content written for publication must have tags that correspond to the intended publications.
Another important setting determines how content is saved. When this setting is on, saving content modules prompts a menu to confirm whether the changes will be saved in the active revision or a new revision. This allows any changes to be directly saved as part of a new revision. When it is off, new revisions must be added before you make any of the associated changes. However, opting for this option ensures that changes related to a new revision are never accidentally saved over the old revision. It also prevents situations where saving does not occur because the confirmation menu was closed before content was saved.
This menu is also used to specify the formats for both the titles of elements and the email message that is sent when content is reserved to a user. The format for the titles of elements in particular is essential to formulate according to your needs with the help of the available variables.
Workflow
DoX CMS lets you complement a few basic features with a custom workflow of your own. Besides committing any changes to the system, you ought to obviously plan how states and reservations will be used to obtain the best results.
The default states in the workflow are (1) Normal, (2) InTranslation, (3) Approval, and (4) Approved. Normal is the initial state. InTranslation is used for revisions in the target language before corresponding translations are uploaded. When translations are uploaded, this state changes according to the specified default transition from this state. Approval shows the content in the Review menu. Approved prevents further editing of said revision. It can no longer be reserved and its state cannot be changed back unless you specifically allow this in the settings.
In addition to these states, it is also possible to, for example, add a state for when content is reserved back to a writer after it is reviewed and changes based on the reviewer’s comments are needed. It is also possible to add a state which shows that the content has been published or a state that tells people that the content is archived. This phase involves considering the workflow from these kinds of angles.
Organization
It is best to plan ahead when it comes to organizing and best utilizing the different views in DoX CMS. This includes lists of (1) topics, (2) tags, and (3) publication templates, as well as (4) folders for attachments.
The views for topics and tags can be freely organized by users themselves. As such, they should be organized based on some principle(s). When the same content gets reused as structured content is expected to be, it is best organized according to subject matter rather than into publications. This allows content for new publications to be located subject by subject. As such, users need then not remember under which publication the contents related to a given subject were organized based on some association. However, when contents are organized based on their subject matter, you ought to consider in advance which subjects are to be used for such distinctions. Subject-specific folders are added in the form of topics that act as higher order categories as part of the list view. Not all topics need to be added to be published. This also applies to, for example, topics which house the sources for content references (conref) and should thus be separated from other topics.
How tags are organized, on the other hand, affects how they function. The tags on the highest level of organization provide names for the main tag categories. You can add sub-categories inside these main categories by organizing tags into more nested levels of organization. Because these tag categories have an effect on how tags function and because tags ought to be added while writing rather than afterwards, it is particularly important to have tags be organized properly in advance.
In addition to deciding on how to organize these views, it is best to prepare means to control these views. This suject is discussed in more detail here. In practice, each list view involves several fields where the values added to them can be used for column-based filters that affect the view. Such fields, including the Description field in both the Editor menu and the Publications menu, can contain keywords, for example, to help isolate the contents that are needed at a given time in the views related to these menus.
How attachments are organized does not differ from how folder structures are used elsewhere. In DoX CMS, you mostly need to account for the possible need to use localized images. Localized images are sets of images from the same folder which have been assigned to show in different languages when contents reference the localized image itself. To ensure that the correct items are referenced from the start, it is best to compose these localized images before the translation process begins for images that contain translatable content.
Preparation Phase
Implementing structured authoring involves procedures which make the early stages more labour-intensive than direct text editing would be. This initial investment repays itself in the form of considerably reduced effort when it comes to maintenance and reuse. Such preparations need only be done once.
The parts that must be prepared in advance in DoX CMS include (1) tags, (2) variables, (3) style sheets (and element classes), and (4) workflow states.
Tags
As is stated above, the implementation for tags includes organizing them appropriately. The required tag categories and tags inside them for products that are already recognized should be added to the system before writing content begins. This allows these tags to be added to content as part of the writing process. If tags will be used in other ways such as to designate the omissions in incomplete pieces of content, the related tags ought to also be added to the system early.
Variables
Since variables are included as part of content proper, they ought to also be set up in advance. In this respect, it is important to have an idea of the types of variables that will be used for each such piece of content. Simple variables are intended for contents that remain uniform across languages. Complex variables include translatable contents that are shared between different publications. Publishing variables, on the other hand, are used for parts that must be controlled separately for each publication. These variables can also be nested inside each other which makes preparing a setup that matches your needs so important.
Simple variables and complex variables also let you apply tag-based conditioning inside them. Further details on this are provided below.
Style Sheets
Style sheets determine the layout and look for your contents. As is discussed here, though, this is a relationship where the contents should also be written with the needs of the style sheet in mind. Readying style sheets also helps you preview content throughout the writing process. When you first deploy DoX CMS, we provide one style sheet based on your needs but you must deliver the specifications that let us write it.
Element classes depend on style sheets for their functionality. As such, they should be specified while the style sheet is being written. You should thus anticipate what kinds of exceptions to general styles and layouts will be necessary. If they are added later, the rules for any new element classes must then be added to the style sheet.
Workflow States
For the planned workflow to be prepared accordingly, you must add the required new states to it and change the settings of existing states. Each workflow state requires you to specify (1) its name, (2) which roles are required for content to be reserved to a user in said states, and (3) available next states. In the case of the InTranslation state, its default transition also matters because the system shifts translated content to that state when the translations are uploaded. The initial value used for this is the Approval state which lets you review content.
Writing Phase
The writing phase also includes features besides adding text and various elements in the editor. The most important such features are (1) content revisions, (2) DITA attributes, and (3) tag-based conditioning.
Revisions
Each content module can be saved into separate revisions from which you may select the one to use in each situtation. Maintaining such revisioning is a part of the writing process because it is often best to allocate changes to a new revision with a description that lists them.
As was mentioned in relation to settings, content revisions can be implemented either completely with the help of the associated command or as a part of the save function.
Editing revisions requires the user responsible to reserve them. This reservation can be left active if the same person will continue editing said content later. Otherwise, is is best to remove reservations from revisions when their content is not actively being edited.
DITA Attributes
In the case of content in the LW-DITA format, a large portion of the related functionality is related to the menus that control DITA attributes.
For example, in the case of image attachments, their addresses are specified as part of the DITA attributes for image elements. The same is true for the addresses of linked targets for xref elements.
Among the most important kinds of DITA attributes are related to the ID field and the Conref field that some element types possess.
ID values are used to reference specific elements. The most common types of such references involve internal links and content references (conref). Internal links move the view to the position of the linked element and content references retrieve the contents of the designated element to be ysed by elements of the same type.
Meanwhile, Conref-values are used for the target elements for content references. These elements’ contents are retrieved from the specified address. This involves adding empty elements in the content and providing them with Conref values which let them retrieve their contents from the elements in the specified addresses. This makes the content of each such target element update when you make changes to their source elements. Such source elements should be separated from the contents that are directly used as parts of publications. This ensures that the original elements need not be located amidst other content when they must be updated.
Tag-based Conditioning
The content modules being written are often intended to be used in more than one publication. You must thus often write sections to be used in only some of those publications inside these modules. These sections must in turn be marked with tags that act as the identifiers for conditiong content in a way that lets you filter it for publications.
Tags can be added both to topics and individual elements inside them. Topics are simplest to mark with the Tags command as part of the list view in the Editor menu because it lets you select more than one of them at a time. To add tags to elements, you select them with the right mouse button and then use the same command on them.
When you publish content, tagged parts that do not correspond to the tags selected for that publication are hidden. Specifically, the contents that will show must share at least one tag with those selected for the publication in each tag category from which they have tags.
Review Phase
You should review material both between and during several of these phases. Once you start writing, though, the systems that support doing so become available.
DoX CMS provides a review feature as part of the workflow to help inspect content. When a topic or a publication is in the Approval state, it will show in the Review menu to the user for whom it is reserved and to all users with a role that lets them view all content under review. This lets you add comments which can also be seen in the editor. The content can also either be approved and locked by changing its state to Approved, or it can be sent back for further editing based on the comments. Users always receive an email when content is reserved for them as part of the workflow.
The previews for publications that are used for review purposes are continuous HTML publications that do not show pages or their headers and footers. You must publish a draft instead to review these details.
Content being written can also be previewed when you use the Publish command in the editor and then the Preview command in the related menu. Doing so shows, for example, how the content layout works with the selected style sheet. The resulting view is not filtered based on tags, though, and links to other topics, for example, cannot find their targets when they are not a part of the previewed content.
In addition to reviewing contents during the writing phase, you ought to do so at least in the case of the publications during the compliation phase and received translations during the translation phase. Even if you cannot understand the language itself, doing so can catch translation errors such as untranslated variables or variables where the identifier inside content has been translated. The latter do not retrieve their proper value.
Compilation Phase
Once the required framework and contents are ready to be used, you only need to compile them into corresponding publications. This involves three steps: (1) assembling topic trees, (2) determining the details of the publication template, and (3) locking the contents of a publication’s revision. The third step is not required to publish content but it ensures that revisions of publications remain the same even when changes are made to their components later.
Topic Trees
Topic trees are sets of topics that are organized to provide the content hierarchies for publications. They let you arrange independently managed content modules to wholes suitable for publishing.
In DoX CMS, topic trees are assembled in their own menu which lets you drag content from the main list of topics and organize it in a new content hierarchy. When you then decide on the details for a publication, this includes selecting a topic tree, from which content that has been conditioned in a different way is filtered out.
Since the contents of topic trees are filtered during publishing, they need not correspond to individual publications. Instead, you can assemble a different topic tree for each type of manual, for example, and include the matching contents for each type of model in these topic trees.
Publication Templates
Once all the required components are ready, they need only be combined into a publication template. Such publication templates are then used to publish the corresponding contents in various formats.
To define a publication template, you need must specify (1) a title, (2) a style, (3) cover pages, (4) a topic tree, (5) values for publishing variables, (6) tags, and (7) content revisions. It is also a good idea to provide a description for the publication template. You can use it to, for example, describe the changes for a new revision or to provide keywords that help find it.
Styles consists of the combination of one or more style sheets alongside page headers and footers. The list of cover pages shows the topics that have been designates as available cover pages, and the selected topics will have corresponding identifiers and be placed appropriately. The values for publishing variables can be specified either separately for each language or as a shared value between all languages. This also holds for the publication’s title.
As is pointed out above, filtering content is founded on correspondences between the tags used to condition content and the tags selected for a publication. Conditioned content shows in a publication when the publication utilizes at least one corresponding tag from each tag category from which the content has tags.
You can select the revisions of included topics that a publication template uses. By default, these values will update to use the newest revision from each content module. However, you can force a publication to use specific revisions either individually or with a blanket command. The available blanket commands are based on principles such as ‘the latest approved revision’ which entails the newest revision that is set to the Approved state.
Locking Revisions
When a publication template is ready and it has been approved during review, it is worthwhile to lock its contents with the workflow feature for publications. If a new version of the same base publication is needed later, this can be done with a new revision of it where its contents will update accordingly.
Individual publication templates act as the revisions for publications. When a specific revision of a publication is set in either the Approval state or the Approved state as part of the workflow, its details will remain identical even if the components in question are changed later. This inclues content revisions, style sheets, attachments (alongside their addresses) and so on.
This ensures that these revisions of the publications will remain as they were during delivery despite any later changes to the used content or styles and such.
Translation Phase
Once publications are ready in their initial language, you can have them translated to other languages as well. This requires you to first define the target language as a means to store related content. Afterwards, you can send a translation request for either an arbitrary set of topics or for each topic included in a specific publication. When these contents are translated, they need only be uploaded to the system which largely arranges them for you.
Languages
Adding a new language to DoX CMS requires providing it with an identifier based on the ISO 639-1 or 639-2/T standard.
When a new language is added to the system, it can be selected as the active language, in which content is shown in different menus, from the top right corner of the main view. Content with multiple languages such as these kinds of variables will also receive corresponding fields where you must add suitable values.
When there are no translations or translation requests with a given topic to the language in question, it will only show the value Not Translated. You cannot open it in the editor before at least one translation request that includes it has been added for that language.
Translation Projects
Translating content involves the use of the Translate command either the Editor menu or the Publications menu. Doing so will initiate a new translation project and either sends the XML file with the content to be translated to the selected user or downloads it.
The translation project must have a name which helps identify it and also acts as its filename. The filename adds the identifier for the target language after this value. You must also specify the target language, who will receive the translation package, and which complex variables the translation project includes.
If this is not the first translation for the content in question, you must also specify what is done to the content in the target language as part of the translation project. Add New Revision adds a new revision with the contents and the revision number from the source language to the target language. Overwrite Revision replaces the latest revision in the soirce language with those of the source language to denote where content should be assigned. This option should only be used when the new translation request is made before the previous translation is uploaded into the system because the original had some error in its contents, for example. Exclude entails that said topic is not included as part of the translation project. This is the default option for revisions for which translation requests already exist. This makes it important that the content to be translated has been approved and and had its state changed to Approved. In this case, changes must be made as part of a new revision which switches the content to be included in translation projects by default once more.
The translations for publications include all topics from which content is used as part of the publication. They also allow you to include a published version of the contents in the source languages as part of the translation package. Another extra command called Use These Revisions in the Translated Publication lets you lock the content revisions that match the settings for the translation project to be used by this revision in the target language. This makes these contents remain in use and correspond to the revision of the publication in the original language despite new revisions being added as part of new translation projects. Otherwise, the publication in the target language uses the revisions of content selected for it. Should none of them have been locked to be used in any preceding revisions of the publication in that language, they will update to match the newest revisions of content in the target language.
You can download the translation package without starting a new translation project with the Preview command. In this case, the revisions in the target language remain unaffected and the system does not add this translation project in the menu to control translations.
This menu lets you re-download the translation packages for existing translation projects.
Uploading Translations
Once the translation is ready, the file with it can be uploaded into the system and its contents are automatically arranged into the correct topics and complex variables in the target language.
You can upload translations on the list of translation projects in the menu to control translations. You do this with the Upload command. When you do this, you can once again select what is done with the revisions in the target language. This time, the default option is Overwrite Revision because by default, starting the translation project involved preparing a revision in the target language with contents that corresponds to those in the source language for the purpose of uploading its translation. In the case of translated publications, the Use These Revisions in the Translated Publication command can be reapplied if what you select here changes the revisions to which the translations are assigned.
Not all content has translations that are assigned automatically. Values that are derived from style sheets require rules for each language in the style sheet. The most common such values correspond to the types of various note elements such as ‘danger’.
Keep in mind that identifiers such as element classes and tags are a part of the content being translated. They are not coordinated between languages outside translations. This is one reason why it is important to ensure that the content in the original language is finished before it is sent to be translated.
As such, even if it is hard to evaluate the language of the translations themselves, there are other good reasons to review translated content. This will reveal if, for example, note elements or variables have no values in a given language.
Delivery Phase
With all the content prepared and quality-controlled, it still needs to be delivered properly, of course.
DoX CMS lets you publish content in various formats and it can be directly sent to the platform of your choice when needed. Otherwise, a local copy of the contents is downloaded for you to deploy.
Publishing content involves using the Publish command in the Publications menu when the correct publication template is selected.
If your instance includes an integration with some specific target system or you use the DoX DMS optional feature, you can select one of these as the target location for publishing in the menu that opens.
You must also select the file format for the publication. DoX CMS lets you publish content in the followinf formats: (1) PDF, (2) HTML, and (3) DITA. There are several available compilers for PDF publications and their availability can be controlled for each environment. HTML content can be published in its basic form or in the WebHelp format. Publications can also packaged in the EclipseHelp format to be opened as single files. The same content can be published separately in more than one format where necessary. We recommend that you use different style files when you do this.
When you publish content, you can change its style to be different from the default style that you defined as part of compiling the publication.
The language for the publication can also be selected when you publish it. Content must have been translated to that language first, of course.
You can specify different values for publishing variables at this point, too. This lets you, for example, specify the name of a customer for a specific delivery even when the delivery is not otherwise unique.
Summary
Structured authoring involves both several preparatory stages and a compilation stage in addition to writing the content. These constitute the workflow that characterizes it, although different systems may implement it differently.
Since structured authoring involves multiple interwoven systems, it is particularly important to plan how to use them in advance. In DoX CMS, this involves user roles, content format and layout, general settings and setting up a workflow in particular.
Planning is followed by having to prepare the parts which will be needed as part of the writing process or in addition to content when you publish the results. In DoX CMS, such parts include the tags used to condition content, the variables that control standardized content, the style sheets that determine layouts, as well as any additional workflow states that are needed.
Once it is time to write content, you ought to keep in mind using revisions to track changes, proper use of DITA attributes such as content references (conref) and ID values, and conditioning situational content with tags.
Both individual content modules and initial drafts of publications can be reviewed with the help of the workflow feature.
In the compilation phase, content modules are composed into publications. This involves putting together a content structure with topic trees, adjusting the settings for publication templates such as selecting tags for them, and locking the values for ready publication templates.
Before content is translated, you must specify the available target languages that you need. Afterwards, sets of topics or all topics related to a specific publication can be sent to be translated in the form of XML files created for this purpose. Once all the content in these files has been translated, they can be uploaded back for their contents to be assigned appropriately in the target language. It should be noted, though, how revisions in the target language are controlled as part of the translation process and how sections derived from style sheets or images, for example, must be translated and set up separately.
Once it is time to deliver publications, they can be compiled by publishing one of the readied publication templates. These files are either downloaded as local copies or sent to other systems that have been integrated with the environment. There are several publishing formats and when you publish content, you can still control details such as the used style.