Editing Guidelines

This article describes the procedure for editing online articles in the IMS Handbook. This procedure aims to ensure alignment with our Writing Principles, for example, in terms of formatting, voice, etc.

For more information on how to use Document360 refer to Getting Started (document360.com).

Opening Articles

Go to the Documents section and open the applicable article. Note: If you imported / created an article and it was imported into / created in the wrong category / position, you can just drag the article to the correct place in the IMS Handbook.

Changing the Editor

Some of our older articles were written with an older Editor. It is advised, when editing one of these articles to change to the new WYSIWYG Editor.

For each article you can change the Editor from Markdown to WYSIWYG:

1. Click the More button in the top right.

2. Click More article options.

3. Click Editor type.

Note

Your article has to be in Draft to be able to change the Editor.

4. Select Advanced WYSIWYG.

5. Check the box to continue.

6. Click Save.

Markdown Editor

We recommend using the WYSIWYG editor, but if you still prefer the Markdown Editor please see:

• The Markdown Guide.

• Using the Markdown Editor in Document360 Editing Guide.

Spellcheck

Document360 makes use of your Browser's spellcheck. Thus make sure your browser is set up correctly:

Article Name / Title (H1)

If needed, update the article name, i.e., title, to ensure it captures enough context. This is Heading 1.

First Paragraph

Make sure you always have a new first paragraph to create the context and orientate the Reader. After an initial paragraph, you can also add a picture / flow diagram to help with the orientation. Make sure the Reader understands how this article fits into the bigger picture. Remember every page can be page one!

Links

We must avoid duplicates in the IMS Handbook. If any content is already covered anywhere else in the IMS Handbook, remove the content from the new article and instead add a link to the article with the original content. 

To add a link:

1. Type “/“.

2. Click Insert.

3. Scroll down and click the Link button.

Aim to always link to a specific heading in an article. This way the reader can quickly find the relevant information.

Preferably the link should open in a new tab, so check this box as well.

You can also link to heading in the same article. In this case, don't check the Open in new tab box.

Symbol Guide

Make sure to follow the  Symbols Guide . 

Make software text fields bold

Take note of the bold that is used to indicate text fields in the software. When updating an old article, please update all the red text in the article.

Adding (side) Notes

In older articles we added notes in smaller text and with a shadow. Note: We set the text size to "14". We have stopped using this. When editing an old article, replace with a blue callout.

Indicating Buttons

Reserve the bold option for Button and Tab names. For example, Click Save. Descriptive names for buttons, shown as icons, should be written in italics. For example, Click the table button.

Indicating an Input in the Software

When the user needs to enter or select an input, use quotation marks. For example, For Equipment Status select "Idle in Place".

Adding Headings

Review all headings inside your article: 

You can use Heading 2, Heading 3, and Heading 4 (the article's name is Heading 1). Heading 2 and Heading 3 will automatically show in the table of content (on the right of your article when published).

Note

If you imported a word document and it was split into smaller articles, you may need to update all the heading levels. So, for imported documents always make sure the highest level headings in your article is really set to Heading 2.

Since articles will be short, there is no need to add heading numbers. Document360 also does not number headings automatically.

Make sure the heading clearly reflects the content that follows. Think about things that Readers search for when deciding on the header. See also Writing Strong Knowledge Base Headings.

Adding Tables

To add a table:

1. Type “/“.

2. Click Insert.

3. Click Table.

To learn more about table formatting see Table.

Format the tables to look the same as the rest of the IMS Handbook:

• Add a header.

• Make sure all text is centered to the left. 

• For big tables make the font one size smaller (14).

In older article we used alternate row shading. We recommend not using this anymore as it can cause issues in dark more. When editing older articles please remove the row shading.

Adding Images

Images are automatically centered and displayed with a shadow. For this reason, do not add inline images, as they will also be centered and may disrupt the text flow. For older article, please fix this.

Avoid using captions unless absolutely necessary. In most cases, captions are not required, as images are shown at the appropriate point in the instruction.

Do not use figure numbers.

To add an image:

1. Type “/“.

2. Click Insert.

3. Click Image.

See Handbook Image Strategy for more information on using visuals in the IMS Handbook.

Adding Equations

Equations cannot be imported. Therefore, all equations must be added manually afterwards.

To add an equation:

1. Type “/“.

2. Click Insert.

3. Click Latex.

Need help with Latex? See:

• Latex equation editor

• Some examples 

• LaTeX commands

In the older articles we added screencaps instead of Latex equations. Please fix when editing an older article.

Bullet and Numbered Lists step-by-step Instructions

For step-by-step instructions, use short actionable numbered lists. Try to always start with the action.

For simplicity and consistency, we always add a period at the end of each bullet.

See Handbook Guidelines: Bullet VS. Numbered Lists for more information on using lists in the IMS Handbook.

Adding Examples

Add example in an accordion (like we did with the above examples). To add an accordion:

1. Type “/“.

2. Click Insert.

3. Click Accordion.

In older articles examples where indicated by a quotation or callout. This option is no longer available in the new editor. When editing an older article, please update the aricle with the accordion.

Adding Videos

The best approach for embedding a video in the IMS Handbook is to first upload it (as an unlisted video) to our Cenosco YouTube channel. You can contact someone from marketing, e.g. Jelena or Monica. 

To embed the YouTube video:

1. Type “/“.

2. Click Insert.

3. Click Video.

4. Enter the video's url.

Note

We prefer not to host the videos in the document360 platform.

Embedding Documents / Files

To embed a file:

1. Type “/“.

2. Click Insert.

3. Click File.

These files must first be uploaded in the Drive, before you can add them.

Please coordinate with the Technical Writers, regarding in which Drive folder to upload the file.

To update a file in an article with a new version do the following:

1. Open the Drive.

2. Find your file.

3. Click on the three dots.

4. Click Replace.

Note

To keep files manageable:

• Do not upload a new file if it is simply a newer version. Instead, replace the existing file.

• Always upload the file to the correct folder in the drive before embedding it in an article.

Rather embed files in the article than adding it as an attachment. It is better to provide the information when it is required. Also attachments are easy to miss.

Adding Acronyms, or Abbreviations, or Glossary Terms

Make sure to add all Acronyms, Abbreviations and Glossary Terms to the Glossary. To do so:

1. Click on the Shortcut button in the top.

2. Click on Glossary.

It is possible to link a term in your article to a term in the glossary. To do so:

1. Type “/“.

2. Click Insert.

3. Click Glossary.

Reviewing Articles

After publishing your article always review it in reader mode. Make sure all text is in the default font. To correct text font:

1. Put the article back in Draft.

2. Select the affected text.

3. Click the Text Format button.

4. Click the Style Correction button.

Setting Status to “In Review”

Depending on your agreement with the Technical Writers you may want to first ask a Technical Writer to review your article

1. Click on Draft (top right).

2. Select In review.

   

3. Click Set status.

4. Sent an email together with a link of the article to the Technical Writer that needs to review the article.

Note

You must send a separate email to the Technical Writer using Outlook or another communication channel.

Although it is possible to tag someone in an article, you should not rely on Document360 to send an email notification.

Adding Comments

You can add comments, similar to in Word:

1. Select the desired text.

2. Click the Comment button.

3. Add a comment and tag a Technical Writer.

4. Click the Send button.

Adding Private Notes

You can also add private notes. These notes are displayed as purple callouts and are visible in the reader view, but only to users with an editor account. Private notes are typically used as reminders for adding or updating content at a later stage, when the required information becomes available. To add a private note:

1. Type “/“.

2. Click Insert.

3. Click Private note.

Publishing Articles

When all is done you (or the one reviewing it) can Publish the article. Remember all Readers will then be able to see this article!!! 

Remember you can always go back to Edit mode when needed and republish.

Now review the published article in the knowledge base.

As a last test, do some searches in the knowledge base and see if the relevant articles are hit. If not, make sure to add the relevant terms to the heading and/or to article content (preferable in the first paragraph).

Adding new Categories to Reader Groups

If you created a new category, then everything in this category will only be visible to Cenosco Readers.

For other Readers, we need to explicitly add the new category to their Reader Groups. If this is needed, contact a Technical Writer.

Adding Tags

Add applicable Tags:

1. Click the Three Dots in the top right

2. Click Tags.

Only select from existing Tags. If a new Tag is needed consult with a Technical Writer.

This can also be done on bulk for multiple articles. To add Tags in Bulk:

1. Click the All Articles button in the top left.

2. Select the desired Articles by making use of the filter.

3. Click Add tags.

Questions

If you have any more questions, feel free to contact me: elsa.tolsma@cenosco.com.