Developer Blog

How To Install Tridion Docs Plugin Template

2021-06-03T17:21:00Z

If you are wondering how to start with a Tridion Docs plugin from scratch? Then here is the solution – To make your life easy our experts have already created the Tridion Docs Publish template. This framework contains the basics to create your ...(read more)

SDL Tridion Docs – HTML output customization - create DITA-OT plugin

2020-07-29T12:19:00Z

Objective Need to customize HTML output when we publish a publication from Tridion Docs. How to Do it We need to create DITA-OT plugin which extends html5 plugin Let’s do it What we need is Tridion Docs installed on server And we should...(read more)

[automation] ISHRemote 0.4 publicly available on www.powershellgallery.com

2017-04-24T11:31:00Z

Introduction...

All of the source code, issues, releases, milestones is all on https://github.com/sdl/ISHRemote

ISHRemote is a business automation module on top of SDL Knowledge Center Content Manager (LiveContent Architect, Trisoft InfoShare).

Your first commands could look like

Install-Module ISHRemote -Repository PSGallery -Scope CurrentUser -Force

$ishSession = New-IshSession -WsBaseUrl https://example.com/ISHWS/ -PSCredential Admin
$ishSession

This library is a relatively thin client layer on top of the business API.

-WhatIf/-Confirm are implemented on write operations.
Add-* cmdlets will immediately create objects in the CMS, and return you an in-memory result holding descriptive identifiers to continue the pipeline.
Remove-* cmdlets will not return any in-memory result.
Set-*, Move-*, Publish-* and Stop-* cmdlets will immediately update existing objects in the CMS, and return you an in-memory result holding descriptive identifiers to continue the pipeline. You cannot use Set-* for creation.
New-* cmdlets will create in-memory objects to locally update and then potentially pass to Add-* and Set-* cmdlets.
Get-* and Find-* cmdlets return existing objects present in the CMS, and return you an in-memory result holding descriptive identifiers to continue the pipeline.
- The Find-* cmdlets was built on top of the API Find operation, which triggers a query to find all objects matching the filter criteria.
- The Get-* cmdlets was built on top of the API Retrieve/Get operations, which trigger a query given object identifiers and then potentially extra filter criteria.
Supports Enable-ISHIntegrationSTSInternalAuthentication/Disable-ISHIntegrationSTSInternalAuthentication as implemented by ISHDeploy.

Other things worth mentioning

Developped Kojak/13.0.0 but will work on 2016/12.0.x and 2014/11.0.x
A lot of Pester-based smoke tests, but probably not enough yet.
New-IshSession received optional switch -IgnoreSslPolicyErrors. IgnoreSslPolicyErrors presence indicates that a custom callback will be assigned to ServicePointManager.ServerCertificateValidationCallback. Defaults false of course, as this is creates security holes! But very handy for Fiddler usage though.
Added Get-IshTypeFieldDefinition and Compare-IshTypeFieldDefinition as web service based alternative for TriDKXmlSetup Full Export, you can even compare setups.

The one where we…

IshSession - New and Changed

Add Test-IshSession which wraps New-IshSession and its variation in a simple test resulting in $true or $false. On the side this is a simple cmdlet that checks if ISHWS and ISHSTS (or other STS) is up-and-running. Together with a simple .ASP call all FrontEnd services can be tested. [#12]
These lines of code activate and hence test the WebServices (ISHWS-activation), SecureTokenServices (ISHSTS-activation) and validates the credentials in the 'InfoShare' database (ConnectionString-activation). The extra .ASP line triggers WebClient (ISHCM-activation) and the COM+ application (Trisoft-InfoShare-Author).
```
  Test-IshSession -WsBaseUrl "https://example.com/ISHWS/" -IshUserName "admin" -IshPassword "admin" -IgnoreSslPolicyErrors -Verbose
  Invoke-WebRequest -Uri "https://example.com/ISHCM/InfoShareAuthor.asp" -UseBasicParsing
```

IshBaseline - New and Changed

Added CRUDF cmdlets for baseline handling. So introducing Add-IshBaseline, Get-IshBaseline, Set-IshBaseline, Remove-IshBaseline and Find-IshBaseline. Allowing you to retrieve you baselines, find the active/inactive ones and toggle their status. [#2]
Added CRUD cmdlets for baseline entry handling. [#2]
- Add Get-IshBaselineItem which allows you to see the versions of the saved baseline entries as you would see them in Publication Manager
- Add Set-IshBaselineItem which allows you to add and update existing baseline entries. So specifically set version for chosen content objects identified by LogicalId.
- Add Remove-IshBaselineItem which allows you to remove baselines entries of content objects identified by LogicalId.

More New and Changed

New-IshSession uses TLS, TLS11 and TSL12 security protocols. SSL3 is removed. Verified with ELBSecurityPolicy-TLS-1-2-2017-01 [#5]
Add parameter argument completion for interactive usage. IshTypeFieldDefinition is now available on every IshSession because of #3. So why not use the field names on ...MetadataField cmdlets and the available LOV on ...LovValue cmdlets when a valid -IshSession is specified. [#11]
For example the last parameters get assistance by using Ctrl-Space or Tab. Note however that a valid $ishSession needs to be available on the command line already.
- Add-IshLovValue -IshSession $ishSession -LovId FirstLetterPlusCtrlSpace
- Set-IshMetadataField -IshSession $ishSession -Name FirstLetterPlusCtrlSpace
Get-IshTypeFieldDefinition should warn that custom fields will be missing. If you really want to load your custom fields setup, you can use the -TriDKXmlSetupFilePath parameter. (To get your TriDKXmlSetup file, you should execute C:\InfoShare\App\Database\Common\DatabaseIndependent\Examples\Full-Export\RunSetup.bat on the WebApp server). [#16]
1. When no -IshSession is provided, the highest local resource is loaded (in practice 12.0.0 standard fields)
2. When an -IshSession is provided but target system is older than 13.0.0, the highest matching local resource is loaded (in practice 12.0.0 standard fields)
3. When an -IshSession is provided but target system is 13.0.0 or higher. The Settings25.RetrieveFieldSetupByIshType API call is used, which includes standard and custom fields.
Tuned Get-IshTimeZone (without -Count parameter) rendering the application server information like timezone, utc-offset and daylight-savings-time. This allows easy load balancer testing. [#13]
The API doesn't allow all fields on the various Create/Read/Update/Delete/Find actions. For example providing a PASSWORD for a user is fine upon Create, but it is not allowed during Read operations. There are many more of these fields where system behavior or business rules are attached. [#4]
- In the past these were hard coded. Now they are routed over the IshTypeFieldSetup class which on 2016/12.0.x and earlier can be initialized by the implicit default or custom TriDKXmlSetup file or starting from Kojak/13.0.0 there is a new Settings25.RetrieveFieldSetupByIshType API call. Remember cmdlets Get-IshTypeFieldDefinition and Compare-IshTypeFieldDefinition available since 0.3
- The ISHRemote client library protects you by default, but if you want to trigger API errors by specifying IShSession.StrictMetadataPreference inspired by $DebugPreference with similar values
  - SilentlyContinue Client-side silent filtering of nonexisting and unallowed fields. (e.g Nice for repository folder syncing with mismatching metadata setup)
  - Continue Client-side filtering of nonexisting and unallowed fields displaying a Write-Verbose message but still continues. Default for 13.0.0 as Settings25.RetrieveFieldSetupByIshType API is available.
  - Off Client-side filtering of nonexisting and unallowed fields is turned off. No handling but simply executes the API call, most likely resulting in a Write-Error. This allows api/pester tests like IshUser PASSWORD field should not allowed to be read. Default for 11.0.x and 12.0.x.
- Set-IshMetadataField that creates metadata fields for Add-*/Set-* cmdlets (Create/Update calls) now removes all value type variations of a field from the collection when adding a new. For example when the collection contains FAUTHOR=VUSERADMIN, a Set-IshMetadataField FAUTHOR=Admin will remove the previous Element value type and add the Value value type. [#14]

Housekeeping

It should be easier to compile the project. Refreshed all ServiceReferences to Kojak/13.0.2803.0 test build and normalized to https://ish.example.com/ISHWS/ including STS urls in http and https flavours. Tuned manifest generator. Code Drift, aligning with legacy Trisoft.Automation module changes for Kojak/13.0.0 (inc up to C59893) [#7|#1]
Added more Pester Tests, current count is Passed: 497 Failed: 0 Skipped: 2 Pending: 0 Inconclusive: 0 where the skipped are about SslPolicyErrors testing.

Feedback...

Any feedback is welcome. As a comment here, in an email. What do you like, what are you missing, etc

Please log a GitHub issue, make sure you submit your version number, expected and current result,...

New versions for ISHServer v1.5 and ISHBootstrap v1.0

2017-04-20T07:00:00Z

This post is copied from New versions for ISHServer v1.5 and ISHBootstrap v1.0. Support for Amazon Machine Image (AMI), Docker containers, Vagrant Boxes and many more.

Background

For those encountering the terms ISHServer and ISHBootstrap for the first time, they are automation modules for SDL’s Knowledge Center Content Manager also identified with the code name ISH.

ISHServer

ISHServer started initially as a PowerShell module that offered cmdlets that aligned with the steps required to prepare a Windows Server for the installation of Content Manager (ISH). This process is discussed in the official documentation and has proven to be error prone. Initially it was part of ISHBootstrap but it was separated, as ISHServer has a more generic purpose and can be used by anyone even without ISHBootstrap. Overtime, ISHServer extended beyond the simple task of automating the pre-requisites installation and server configuration.

ISHBootstrap

ISHBootstrap is a PowerShell script library that drives the flow. It has the ability to bootstrap a clean Windows Server instance into a fully operational server with Content Manager (ISH) deployments. The supported operating systems are Windows Server 2012R2 and 2016. The bootstrapping can be executed locally or against a remote server using Windows remoting. ISHBootstrap has embedded an examples directory to showcase how the complete process could be represented and executed by a json file, but keep in mind that this is just an example. By default the instance of Content Manager has zero configuration applied to it, a state that is also known as the Vanilla deployment. The examples folder in ISHBootstrap offer a collection of ISHDeploy scripts that showcase certain configuration examples using scripts that use ISHDeploy cmdlets. In general, ISHBootstrap scripts are a very good example of how to use ISHServer cmdlets. Although disconnected, I would advice always to use ISHBootstrap over ISHServer.

New features

The main mission of ISHServer has been accomplished since its first stable version. Usually all enhancements to the module are in favour of supporting enhancements for ISHBootstrap when the functionality is considered generic enough. With the latest version of 1.5 those additional features are summarized as:

Support for FTP, Amazon S3, Azure Blob and File storage as source for the dependencies, ISH CD and AntennaHouse license.
Create, update and initialize the user account that is used for Content Manager’s processes.
Download and expand the Content Manager CD in a consistent manner.

All above features are developed to support execution under the following conditions:

Local administrator.
Windows Remoting. This is important because packer uses windows remoting to provision scripts while initializing an Amazon AMI or an Hyper-V instance.
Local SYSTEM account. This is important because for Amazon EC2 instances, both the userdata and CodeDeploy execute under the SYSTEM account and this really complicates things a lot. I’ll try to make a post about the difficulties we faced when executing under the SYSTEM account.

ISHBootstrap had always the ability to prepare an operating system with a fully operational Content Manager. With the first stable version 1.0, ISHBootstrap is now able to do something slightly different but very important. It can prepare a Windows Server instance with an almost ready Vanilla deployment.

What is an almost ready Vanilla deployment?

The last step of installing Content Manager takes around 5-6 minutes alone. We also need to consider that the installer was not build for producing a deployment that just needs a couple of parameters to very quickly become operational but it always approached the problem as from zero to all. But when working with cloud services and containers that is not acceptable. Imagine a docker container that takes 5-6 minutes to run, because it needs to install Content Manager first. Same concept applies for cloud and vagrant boxes. You need something that is ready to launch as quick as possible. In my experience the containers technology is the best advocate of this concept. For example Microsoft’s SQL Server container image, is in kind of almost ready state because the services are not running, the sa password is not set and only the master database is available. It is the job of the initialization script to fill in this gaps and provide an operational SQL Server as part of the container’s run step. Imagine the container installing SQL Server when running. Imagine the delay. This is exactly what we want to avoid with Content Manager. They are both fairly complicated products to install with a time consuming installation process, that we don’t want to spend every time we want to run the instance.

To solve this problem, ISHBootstrap introduces the Builder concept. The builder concept works around the limitations of the installer of Content Manager by producing a reusable template of one Content Manager deployment, that previous was referred to as almost ready. It actually mocks temporarily certain dependencies to allow Content Manager’s installer to execute and then clears them out. At this point the deployment is inoperable just because the mocked dependencies used are already cleared out. To turn this non-operational deployment into a operational one, a script is provided that will replace the mocked values. This last step could be considered as the run step of this almost ready artifact. The process is very similar to the sql server image but is not restricted to docker containers only.

The produced artifact can one of the following:

Amazon Machine Image (AMI). An AMI can be used to spin up an Amazon EC2, that is a Virtual Machine. As the AMI includes all the time consuming process, the EC2 instance is ready for use in the least possible amount of time.
Vagrant Box on top of Hyper-V. A Vagrant Box can spin up virtual machines for any host. As the box includes all the time consuming process, the VM instance is ready for use in the least possible amount of time.
Docker Container. This is for experimentation and learning process.

Each of this types of artifacts is ready to become operational by providing the following parameters

A db connections string.
A user to run Content Manager processes, known also as the osuser.
A hostname.
A valid certificate for the hostname.

The builder concept goes even one step further and can embed a local sql server express in the artifact. This is not meant for production purposes but if you want to quickly spin up an SDL Knowledge Center instance as a Hyper-V VM, or Amazon EC2 or a container, then you don’t have to worry about the external dependency to a database server. It’s already ready and executing. I’m actually looking for ideas to reduce dependency to the rest of the parameters for this use case. For example hard-code the osuser’s credentials.

Unfortunately this is not yet possible for the Vagrant boxes because we are facing problems installing the database as part of the packer provisioning process. Luckily, very good workarounds exist for AMIs and containers. Amazon offers windows AMIs with SQL Server Express already installed and for containers, I’ve created this asarafian/mssql-server-windows-express:2014SP2.

Before I mentioned that the container variant is not to be used in production because Content Manager needs to go under some core architecture changes to become more container friendly. It’s not that it won’t work as far as ISHBootstrap is concerned but ISHBootstrap cannot and will not amend any core product limitations. As with everything, try it out but if you productize it, then the risk is yours.

With that in mind, I find containers an amazing learning tool. The docker team, has actually solidified the concept of image and instance but more importantly they fully support inheritance between the containers. This means, anyone can use as starting point a container that someone else has created. As such, a Content Manager image would be an excellent starting point to create customized images ready to run. To be fair, Amazon had already achieved this with the Amazon Machine Image technology but it’s still virtual machine technology based and kind of dirty. As far as I know packer and vagrant don’t support this model and this is the reason there isn’t yet the ability to produce a vagrant box with SQL Server embedded.

The business case driving the features

SDL is moving to the Amazon for various reasons and there can’t be any cloud without full automation. During the last year, I’m driving the DEVOPS angle for Knowledge Center by making sure that we (the engineering team) produce the necessary tooling for automation such as ISHDeploy, ISHServer and ISHBootstrap. My colleague Dave De Meyer, is also pushing the ISHRemote PowerShell module. Although DEVOPS is focused on operations, I’m a believer that DEVOPS should be a mental approach embraced by all software engineers involved. It should be a discipline of “Automate as much as possible”. For this reason, the automation toolkits are not specific only to DEVOPS nor to a specific cloud provider and can be used by anyone to improve the interaction with a Content Manager deployment. The main goal is to help everyone improve their interaction with Content Manager by automating the uninteresting and error-prone steps. Therefore, I think that a ready to launch deployment is a great offering.

Concepts such as containers, AMIs and Vagrant Boxes can become the deliverable and replace the old fashioned CD that as an approach is too error prone. Instead a ready to execute artifact has much less chances to go wrong.

As SDL is moving to Amazon, we need to build AMIs that allow the creation of a cloud formation stack within a reasonable amount of time. ISHBootstrap’s codebase is the main engine for SDL’s AMI builder process. The only difference is that here at SDL we want to hard wire certain dependencies for ISHBootstrap and Content Manager where ISHBootstrap uses the latest and greatest.

I’ll provide some rough numbers to understand the significance of having a ready to launch template such as an AMI, Vagrant Box or docker container. The following table presents the amount of time in minutes required to get an operational Content Manager deployment with and without the builder concept.

Platform	Host type	Full ISHBootstrap	Template Type	From Template
Amazon	EC2	45 minutes	AMI	10 minutes
Docker	Container	30 minutes	Image	1 minute
Vagrant	Hyper-V	45 minutes (*)	Vagrant Box	5 minutes

(*) Both with Amazon and Docker, we usually get the operating system with all the latest updates. But with Hyper-V that is not true. Installing the latest windows updates on Windows Server 2016 takes an additional of 1 hour minimum. That is a lot of time to waste if you ask me.

Sadly at the moment of writing this post, the containers are not fully tested. They build just fine but something during the run step does not allow them be become operational. This is probably because the necessary parameters required are too many and a mix of filesystem and in memory variables. The reason this didn’t stop us from releasing is because containers have an experimental and learning purpose and therefore a lower and non-blocking priority.

Start using ISHBootstrap - Get in touch with your SDL liaison.

Some basic documentation is available on ISHBootstrap’s tutorials section. The main limitation is that the server dependencies for Content Manager and the CD itself are not freely accessible to everyone. If you want to get access to these files, then you need to address your SDL contact. Although the dependencies can become public, the current policy of SDL restricts the CD of becoming one. For this reason using ISHBootstrap requires some initial alignment with your SDL liaison.

For the same reason any artifact such as an AMI, Docker container or Vagrant box will not be published as it implicitly contains the above. Instead, you will have to build them using your provided access.

Extending your deliverable

As with containers, the generated artifact can be extended and modified in composition. For SDL’s cloud, we actually do this but the core implementation is common and resides in ISHBootstrap. In the same manner, you can extend the process to produce your own customized AMIs, docker containers or Vagrant boxes.

ISHBootstrap and ISHServer we’ll do the heavy lifting and you just need to add the extra magic afterwards.

Released ISHDeploy Powershell module version 1.3 for code as configuration

2017-04-18T07:27:00Z

Please refer to previous release announcement for some background information regarding ISHDeploy.

With this new version, ISHDeploy helps configure and control the state of the Translation Services. All cmdlets are fully documented online and code oriented tutorials are also provided.

Integrating translation jobs with SDL World Server.
Integrating translation jobs with SDL TMS.
Exporting translation jobs to the file system.
Configuring the services.
Scaling the services.

With the new release, the following modules are available in PowerShell Gallery for the respected versions of Knowledge Center

ISHDeploy.12.0.0 for Knowledge Center 2016 Content Manager
ISHDeploy.12.0.1 for Knowledge Center 2016 SP1 Content Manager
ISHDeploy.12.0.3 for Knowledge Center 2016 SP3 Content Manager

More detailed release notes are available online at https://sdl.github.io/ISHDeploy/12.0.3/. If you are using a previous release, please refer to the main overview section of SDL's open source initiatives. A list of all modules on PowerShell gallery is available with this query.

New release versions for ISHServer (v1.1) and ISHBootstrap (v0.7)

2017-02-06T14:08:00Z

Following Frank Closset announcement Did you know… we are working on PowerShell automation libraries that we are working on PowerShell automation toolkits I would like to share with everyone the availability of new versions for ISHServer and ISHBootstrap.

ISHServer v1.1

ISHServer is powershell module that automated the preparation of a clean Windows Server operating system.

Currently only ISHServer.12 is available in the PowerShell gallery to align with SDL Knowledge Center 2016 releases for Content Manager.

This module has been available for sometime already but the new version 1.1 adds two new interesting options:

Support for Amazon AWS S3 buckets for the files it depends on. That is for the cmdlets that download the Prerequisites, the CD and the AntennaHouse license. The functionality was already present for FTP sources.
Support for the provisioning of the Content Manager (ISH) CD. This is brand new. Get-ISHCD is the cmdlet to look into.

ISHBootstrap v0.7

https://github.com/Sarafian/ISHBootstrapISHBootstrap offers the tooling for an end to end SDL Knowledge Center deployment. It depends on ISHServer but it does so much more.

- For systems with PowerShell version 4, it will install the necessary components for PackageManagement.

- Install the necessary powershell modules. e.g. ISHServer and ISHDeploy depending on the version.

- Install the prerequisites and run the server's configuration

- Download and expand the CD

- Install the CD

- Run the ISHDeploy configuration scripts

All the above are "remoting" enabled and can be executed locally or while targeting a remote computer.

Also, each step is backed by one or more scripts so the ISHBootstrap provides the necessary level of granularity for anyone to build a his own orchestration. That can be Chef, AWS cloud formation and code commit, Azure, Puppet Vagrant etc

ISHBootstrap comes with a small orchestration example repository that is powered by a JSON file. There is a How to use the repository (Examples) tutorial.

ISHBootstrapDemo

If you want to do a quick demo dry run then take a look at the ISHBootstrapDemo. I created this repository just before the SDL Connect summit to showcase how easy it is to fully bootstrap an empty Operating System. The repository has an embedded JSON file that shows has simple it is. Please take notice that the example is based on SDL's ftp and you will need to provide you ftp credential. Also, there is an expected structure on the FTP server that is not currently available for all FTP accounts. Please ask your support engineer to make the necessary artifacts available for your account also.

Did you know… we are working on PowerShell automation libraries

2016-12-15T16:54:00Z

People, by nature, don’t like repetitive tasks. Even worse repetitive tasks will often lead to humans making mistakes: someone forgets to copy a file, someone forgets to set a setting. To manage growth and taking cost out while managing your IT landscape, automation will be key. It will improve accountability, efficiency and predictability, while reducing cost, variability and risk.

Our team has been working hard on a number of libraries to help our customers automate and manage deployments of SDL Knowledge Center. The libraries are available as PowerShell modules. PowerShell is a powerful scripting tool that is becoming the ad-hoc standard for anyone managing and automating a Microsoft ecosystem.

These libraries are made available as open source initiatives on GitHub. When companies think of open source, these days they think "business agility," a quality they increasingly value above all others in the fast-changing marketplace… and that’s not different for SDL.

The following libraries are available:

ISHRemote
PowerShell module that provides a scripting alternative for our Content Manager API. Everything that will be possible through the API will be possible through PowerShell. This module will help you to automate, for example, publishing documents, changing data already in the database, importing content, exporting metadata, provisioning users, and so on. For more info, see https://github.com/sdl/ISHRemote.
ISHBootstrap
PowerShell script repository that aims at fully automating the installation and configuration of SDL Knowledge Center. Ultimate goal is to be able to spin up new Knowledge Center servers on demand and take them down when needed. Initially, the module will focus on the Content Manager part. For more info, see https://github.com/Sarafian/ISHBootstrap.
ISHDeploy
PowerShell module that provides the necessary tooling to configure Content Manager of SDL Knowledge Center in an automated way. Our goal is to allow continuous deployments and to prevent configuration drift. This module uses the “Code as Configuration” principle as a guideline. “Code as Configuration” means that you will need to express your configuration in a PowerShell script and that you no longer need to know which configuration files to change, which services to restart, and so on. Configuration scripts will be cross-version compliant as long as the referenced feature is compatible with that Content Manager release. For more info, see https://github.com/sdl/ISHDeploy.

Ooh, and finally, open source wouldn’t be open source if weren’t welcoming contributions from the community.

ISHDeploy PowerShell module for code as configuration is now on version 1.2

2016-12-15T10:06:00Z

ISHDeploy PowerShell module. What is it and what does the new 1.2 version offer.(read more)

Best practices for XML editing experience in Knowledge Center

2016-11-03T08:28:00Z

Even though Knowledge Center comes with Content Editor preconfigured for the basic topic types, it is worthwhile to try to optimize the experience for people working with the editor. It will depend on your organization and your documentation what DITA elements are used and how they are used. Based on that you can tweak the experience using the methods described here. When you are using specializations it becomes even more important to look at how this is influencing the editing experience.

Visual design

The look and feel of any application has a big impact on the user experience. If something looks good, it generally is more pleasurable to work with. In the case of Content Editor, the document itself takes up the biggest part of the screen. So the visual design of your documents is very important for the overall look and feel.
The best practice is to align the display in the editor with the most common final output. If that output is html you could match the target styles completely, or even reuse the stylesheets. If your users see a pdf or print version of the content as the leading output there might be things you cannot do in the editor, for example pagination. But matching fonts, sizing and colors will already give a familiar feeling to the editor.

Show structure

If you want your users to create documents in the correct structure, they need to be able to understand the structure. This by no means has to be showing the underlying XML structure, there are more friendly ways of doing this as well. Which way to use depends on both the targeted users and the type of content.

Formatting

The most common way to show structure is to change the formatting. Everyone will understand that text that is displayed in a larger bold font is a title, since this is something we learn by reading books and seeing this being used all around us. This works well for all things that are common and easily recognized, like titles, lists and so on. Other elements, for example sections like Prerequisites and Context in DITA tasks, are not as easy to recognize from their styling alone. In those cases the styling is not conveying enough information about the structure and you will need to use other ways as well.

Placeholders

When an element is empty, placeholders can give more information about the type of content that is expected in this element. This will show for example the element name in grey text, and allows the user to click on that text and start entering content. But as soon as the user starts typing, the placeholder will disappear, and the information about the structure is not visible anymore. This makes it a good tool in addition to the other clues described here, but should not be used as the only way to show structure.
Read more about using placeholders in Content Editor.

Labels

Where styling works well for common structures known from for example Word, labels are crucial for less common elements. Labels provide more information about what content is expected. Examples here are metadata elements, but also sections with special meaning like Prerequisites and Context in DITA tasks. By showing labels for these elements, you can offer a form-like interface, which works well for these type of elements, where formatting alone is not enough to make them clearly identifiable. By using a form metaphor, you make working with these less familiar elements easier by using a familiar interaction pattern.
This is a step away from WYSIWYG, but this is not a bad thing. Better keep the good parts (easy recognition by using familiar styling), and throw away the bad (not enough clarity on document structure). In many situations there are also multiple output targets, resulting in people coining terms like WYSIOO (What You See Is One Option), and realizing that trying to be 100% correct is not the right goal.

Tags-on view

This is a more generic way of showing structure, while keeping the styles of the normal document view in place. While this is a great way of looking at the document for certain users, it is not the most friendly display for people who are not used to this. This should be used in addition to the other methods of showing structure written above, and should not be considered a replacement for them.
The Xopus tags-on view can also be configured to show tags for certain elements only, so you can also use a hybrid solution where well-known elements do not have their tag shown, but lesser known and harder to recognize elements do.
Read more about using the tags-on view in Content Editor.

XML view

This is the most direct view on the document structure, but because of the uniform styling of the data it is not the easiest to work with and recognize the different elements. For many users, the XML view looks too complicated to be useful. If the display stylesheets are written correctly, your users should not have to use this.

Do not start with an empty document

Content Editor will only add elements automatically when the schema requires those elements. So if your schema doesn't require any content, give your users a head start by setting templates. You can configure a template in Content Manager to define the structure for new topics. On a smaller level, you can configure templates for elements in Content Editor. This will tell Content Editor what child elements to insert when a user inserts that element. Required child elements are always added, but this way you can insert optional child elements as well, for example a title element in a figure.
Read more about using templates in Content Editor.

Ribbon toolbar & menus

You can modify the ribbon toolbar to allow easier access to commonly used elements. And at the same time you may want to remove some elements from the ui that will not be used that often, or are even discouraged from being used by a styleguide.
You have several tools at your disposal to make these changes. First of all for the ribbon you can use the overlay mechanism to add/remove individual buttons, but you can also create a completely new tab, like we have done for the "task" topic type.
To modify the right click and breadcrumb menu's and the dropdowns of the "All elements" group of the insert tab, you can use the configuration. Use the "hidden-from-ui" role on the elements you want to hide in these menus, and use the uiGroup configuration option to divide your elements up into multiple groups.

Add accelerators for often used actions

Last but not least, take a look at what editing operations your end users need to do most. Do they often need to add new sections to a document? Consider adding a button right there between the existing sections to add a new one. The generic schema-based UI is effective for accomplishing most tasks, but with a little more knowledge on what matters most to your users you can greatly speed up their tasks by adding additional tools.
Read more about using the Content Editor API from the XSLT.

These are some important things to consider to get the most out of Content Editor. Do you have more tips for your fellow Knowledge Center developers? Let us know in the comments below! And if you need any assistance in implementing any of those tips, feel free to ask for advice on the forum.