Assist Editing Guide

General

Before editing, you should log in - the Assist system will not allow you to edit the documents unless you have, so that all changes can be tracked to the user that made them.

Document Editing

When you find a page that needs editing, you can do it in one of to ways:

Source Editing - typing in plain text with WikiText markup language - not too complicated, but a bit of a barrier for new users. Click the Edit Source button to start source editing.
Visual Editing - like a simple version of your favourite document editing application. You can do most things (but not all) with Visual Editing. Click the Edit link against a page to start Visual Editing.

You can also flip between visual and source editing when you're in there, so don't worry if you clicked the wrong one.

This guide will show you how to do everything here in each of the editing methods, to help reduce those barriers and make documentation easier.

Source Editing

WikiText markup can seem daunting, but it's not meant to be. This guide won't try and describe everything that you can do with WikiText markup, but will describe how the tools can make it easier to do.

This section will introduce you to the source editing toolbar and some basic concepts.

When source editing you will have a toolbar for basic edits. So start typing, and when you want to format something, you can use the toolbar.

If I want something in bold, I click the Bold Text button - the WikiText markup will be put in the editing window for me, with the text in between the markup ready for editing.

The same is true for:

Italic text
Headings (level 2-5)
Bulleted lists (like this one) or

Numbered list items like this one

No Wiki formatting (turns off WikiText markup, hugely useful when writing a guide like this one!)
New Line
Big text or Small text
^{Superscript text} or _{Subscript text}
Links to other pages, like Did You Know.
Code.
"Noinclude" tags.

You can also highlight the text you want to format and then click the button - the editor will tag the text you highlighted.

You have a Preview button - this shows you what you're WikiText changes look like in real formatting in near real time. You can't edit it there. but it's useful to see you're getting it right.

Other essential page formatting is more complicated:

Tables can be inserted easily enough using the Table button. Click the button, choose your number of columns and rows (and any properties of the table, like sortable) and click Insert. The editor will insert the table for you in shorthand, like below:

Caption text
Header text	Header text	Header text
Example	Example	Example
Example	Example	Example
Example	Example	Example

Then you can edit it. We typically do not use captions, so you could remove that line if you want. To change the cell content, simply change the text between the vertical bars (or exclamation points, if it's the header row).

Tables also support being searchable - it's not a property that is supported by the Table tool, so you have to edit it in yourself.

Add "apt-searchable" to the table class

 {| class="wikitable apt-searchable"

You can then make rows non-searchable by adding a class to the row "|-" element as follows:

 |- class="non-searchable"

Images are covered in a following section.

Visual Editing

Visual editing formats the text like it would do on the final page (in most cases). It's almost completely invisible to you as an editor that in the background this is generating the WikiText markup for you, so makes it much easier. There are however some things that the Visual Editor can't do which source editing is very useful for.

This section will introduce you to the visual editing toolbar and some basic concepts.

When visual editing you will have a toolbar for basic edits. So start typing, and when you want to format something, you can use the toolbar or the provided shortcuts.

If I want something in bold, I click the Style Text button and choose Bold or press CTRL-B - the text I type will be in bold from now on. You can turn it off in the same way.

Note: The visual editor can use keyboard shortcuts, and the editor will tell you the shortcut keys next to the toolbar option you are selecting, if there is one.

Standard shortcut keys are also supported, like cut/copy/paste:

CTRL-X - Cut.
CTRL-C - Copy.
CTRL-V - Paste (formatted).
CTRL-SHIFT-V - Paste (plain text).

Additional formatting:

CTRL-I - Italic text
Big text or Small text
^{Superscript text} or _{Subscript text}
Computer code formatting
CTRL-U - Underline

and many more.

You can also highlight the text you want to format and then click the button - the editor will tag the text you highlighted.

Similarly with links to other pages, like Did You Know. Either click the Links button in the toolbar, enter the page name and click Done. You then have the opportunity to edit alternative text directly over the link. The same is true for an existing link when you click on it.

Bullets and numbered lists (and indentation) can be accessed from the Structure button.

Bulleted lists (like this one). There's no shortcut key, but you can start a bulleted list by entering an asterisk followed by a space.

Numbered list items like this one. There's no shortcut key, but you can start a numbered list by entering a number followed by a full stop and a space. Or a hash symbol followed by a space for a new numbered list.

Paragraph formatting can be accessed from the Paragraph Formatting drop-down list in the toolbar.

Headings (level 2-5)
Preformatted Code formatting
Centre text

and many more.

Warning: You currently can't mark anything as nowiki formatting, or as noinclude. Sorry - you have to use the Source Editor for that.

You have undo and redo buttons (and their normal shortcut keys (CTRL-Z and CTRL-Y).

If you are familiar with WikiText markup and start typing in the syntax from WikiText (like {{ to insert a template), the Visual Editor is going to recognise that and either format the text or popup the dialogue associated to that WikiText markup - in the example above, it will open up the Insert Template dialogue for you, so the markup can be used as shortcuts in most cases. It doesn't work for bold and italic or images, but pretty much for everything else, so handy to know.

If you paste WikiText markup from source editing into the Visual Editor, it will convert the text for you, rather than see it as plain text - super useful when copying between pages.

Other essential page formatting is more complicated:

Tables can be inserted easily enough using the Insert button and selecting Table. Click the button and a table is inserted into the page.

You can use the buttons to add columns and rows. You can also edit the properties of the table with the Properties button, for example, to get rid of the caption if you don't want it.

Editing the contents of the table is directly in the cells themselves - much easier.

Warning: Unfortunately, you can't (yet) add searchable tables through the visual editor. Worse, the visual editor may remove your searchable tables code when saving the page, so a bit of a downside.

Images are covered in a following section.

Standards

To maintain a fairly standard set of documentation, use the following guidelines:

Buttons should be in Bold.
Tabs and menu options should be in italics.
Keyboard shortcuts or code should be in Code or Preformatted format.
Leave two lines between sections.
Use templates - see Templates section below.
Reuse documentation where possible - if there is already a page describing how to use or do something, include that page - see Transcluding below.

Images

Images must be uploaded to be used in pages, which is a bit of a pain, but really aids in reusability of images.

Warning: Bear in mind that, with either Source or Visual editing, you can't trim or edit the image when it's uploaded, so make sure what you're uploading is what you want to see in the final document.

Warning: Be very wary of using scalable graphics formats, such as SVG. Although they look fine in the web pages, the images do not render in the PDF print at this time.

When source editing:

These images need to be saved first.

Easiest is to use an image editing application such as MS Paint, which makes this fast and easily editable.

Take a screenshot of your screen (CTRL-PrtSc) or the active window (ALT-PrtSc).
Paste into Paint.
Crop and Save to a local file - use PNG format by preference.

Alternatively, use the Windows Snip and Sketch tool to do the same.

Clicking the Image button will show a dialogue to enter:

Filename: enter a filename for an image that has been uploaded, or enter a new name. Keep it relevant, like "VEhub_Login.PNG"
Caption: optional
Alternative text: optional
Size: optional, but any image that you ware uploading that is greater than 1000px wide should be reduced to that or 800px, to make them fit in the PDF when produced.
Align: Left, Center, Right or None.
Format: Choose None.

You have an Upload button here, so you can upload the image you have already saved to your PC.

When visual editing:

You have lots of options to create a new image.

You can take a screenshot of a screen or window as above or copy an image from a document or filesystem, then just paste (CTRL-V) in the editor - the Image dialogue will appear, showing a thumbnail, allowing you to name the image, then edit any properties. Steps:
- Paste the image - the image popup will appear.
- The image will initially be named "image.png" - that's OK, as we will change it in a minute - Check "This is my own work" and then click Upload.
- Enter a name - make sure that this is unique and relevant, , like "VEhub_Login.png" or "Tesla Order Search 1.png".
- Enter a description - the dialogue forces you to enter a description - you could just copy in the filename, or (preferably) enter a description, maybe also a unique ID like the screen name.
- Click Save - the properties box will be displayed - see below..
You can drag and drop a local image from your PC straight to the window. When you drop it, the Image dialogue will appear, showing a thumbnail, allowing you to name the image (which will default to the name of the file being uploaded). From that point, it's similar to the above process, of uploading, naming, saving and editing properties.
You can choose images you have recently uploaded by selecting the Insert button on the toolbar and selecting Images and Media. You can then select the image from the Search tab, select it, click Use this image and then amend the properties. This is super-useful when combined with batch uploading of images (below).
You can choose to re-use images that have already been uploaded onto the Assist by anyone - select the Insert button on the toolbar and selecting Images and Media. You can then search for images by their name from the Search tab. When you find an appropriate image, you can select it, click Use this image and then amend the properties.
You can directly upload a saved image by selecting the Insert button on the toolbar and selecting Images and Media. You can then select the image from the Search tab and then amend the properties.

The properties you can edit are:

Caption: optional
Alternative text: optional
Position: Left, Center, Right or None. Choose Center or None. If will turn itself off if you select a Basic image.
Image Type: Choose Basic.
Image Size: optional, but any image that you ware uploading that is greater than 1000px wide should be reduced to that or 800px, to make them fit in the PDF when produced.

Then you can insert the image.

For updating an image that already exists, however, your options are more limited. It's important that we update images, rather than upload new ones. If you attempt to paste in an image and call it the same thing as something that already exists, Visual Editor will throw an error.

To update the image, you have to save as a picture file first:

From a Word document, right-click, Save as Picture, give it a name and save.
From printscreen, paste into your paint application and save as PNG.
From Snip and Sketch, save as PNG.

You can then:

click on the image link and upload a new version from the upload page.
click Upload File from the Wiki Tools toolbar on the left and upload a new copy.
batch upload the file - see below for details.

Regardless of which editor you are are using, you also have the ability to batch upload images. So, if you have created all the images you need and named them appropriately, you can upload those images using the Special page "Upload Multiple Files". From there, you can drag and drop or multi-select all of your images into the system, then use them in your page.

Save your images to local files in a unique and reasonable filename - if it's reusable for other things, make them relevant, as above.
- From a Word document, right-click, Save as Picture, give it a name and save.
- From printscreen, paste into your paint application and save as PNG.
- From Snip and Sketch, save as PNG.
Go to the Assist Special pages
Select Upload Multiple Files
Enter a description if you want - it's optional, but can be useful. For example, if uploading a load of images relating to a Tesla Support document, you might enter "Tesla Support Images". But you can also leave this blank - that's perfectly fine.
Either
- Select all your images in a Windows explorer and drag and drop to the appropriate place on the page
- Click the button, multi-select from the popup explorer and confirm.
The files you selected will be shown in a list on the page.
As they are uploaded, they will change colour to show whether they uploaded successfully or not
- If they turn green, all good.
- If they turn red, they didn't upload - check the error reason and correct.
Warning: Uploading a file that already exists will create a new version of that file - you should check where this image has been used before and make sure that the image you have uploaded is appropriate to all pages that use it.

Templates

Where possible, the templates created for you should be used when creating and within the document.

We use Templates when we want a consistent look to certain things, from simple things like a notation, to more complicated things like a full document.

You can add templates quite easily:

Source Editing:
- Just type in double-curly bracket notation like {{Warning}}
- Or Click the Template button, type the name or part of the name of the template you want to use, for example "War" then select it and Insert.
Visual Editing: click the Insert toolbar option, then Template. Type the name or part of the name of the template you want to use, for example "War" then select it and Insert.

Some more complicated templates have parameters that can be passed to them. In the example above, "Warning" can accept a single parameter of the warning text itself. It's optional in this case, but some really complicated templates (like Doc Title) have lots that are required to be entered - you use it like this:

Source Editing:
- With positional parameters, just vertical bar delimit the parameters like so: {{Warning|My warning text}}
- Some templates support named parameters, like so:

{{Xref
|Type=Example
|Num=1
|Text=The text describing the cross-reference
}}

- Or Click the Template button, type the name or part of the name of the template you want to use, for example "War" then select it. You can then enter the parameters and Insert.
Visual Editing: click the Insert toolbar option, then Template. Type the name or part of the name of the template you want to use, for example "War" then select it. You can then enter the parameters and Insert.

Some simple templates:

Note - This provides a note graphic Note: like so
Warning - This provides a warning graphic Warning: like so
Hint - this provides a hint note Hint: Like so.
Xref - this provides a cross-reference in a standard format. Use it like so: {{Xref|Type=Image|Num=1|Text=An image of something}}
Incomplete - this adds a warning that the document is incomplete, and adds the document to an Incomplete category, so it can be easily found and completed. Use it like so: {{Incomplete}}
Generic glossaries have been provided for the CALIDUS products -
- You will find them in the Glossaries category.
- These can be added to and amended if required by clicking on the glossary template in the editing screen.
- Note: All Glossaries are now maintained in this Assist, the Calidus HUB. That means that you can add them to your pages or documents or refer to them, but they are all referred to as part of the "obs" namespace. This is a special bit of functionality known as Interwiki, and is dealt with below.
Test Plan templates are available to construct test plan cycles - see the Functional Specification template for details on how these work.
A Comment template has been added to identify comments added to a reviewed document easily

like so
—User:Anw, 31/1/2012 16:33:36

Some complicated templates:

Doc Title - creates a document title page.
Doc Appendix - creates a document appendix page.

Some full document templates: Document templates have been produced for the following document types:

Requirements
Estimates
Functional Specifications
Small Change Requests
Test Plans
ERs
Patches

and many more.

Full document templates can also be accessed through the Help:CreateNewPage page.

The links on that page will help you generate a new document or page.

Enter the title of the page or document you are creating in the right entry box for the document that you want to create.
Click the button.

The system will copy everything required in the template into a brand new page created for you, so that you can complete editing it.

There are pretty extensive guides in the Assist category on creating pages (specifically release notes) from Templates - it is advised that you look there for more information.

Transcluding

Tranclusion is all about re-using pages that you have already created. We can (and should) do this, as "edit once, edit everywhere" applies, meaning that the pages are updated in every other page or category that uses them, massively reducing the amount of effort required to get changes into the right places.

Say for example, you have documented the Resource Allocation process in a page called "Allocate Resources". That screen is called from the Planning Screen and from the Waterfall screen, which are also documented. You want to describe resource allocation in the documentation of those pages, but you don't want to have to type it all in again, or have to keep updating multiple pages because a small change has happened to that Resource Allocation screen. You could just add it as a like , for example, "see Allocate Resources for more information", but you really want a complete document here. Transclusion helps here.

In the Planning page, you add a Header for "Allocating Resources"

Source Editing: == Allocating Resources ==
Visual Editing: Choose the Heading 2 format from the toolbar and type "Allocating Resources".

Then we can transclude the page:

Source Editing: {{:Allocating Resources}}
Visual Editing: On a new line, click the Insert toolbar option, then Template. Type a colon, followed by the page e.g. :Allocating Resources, then select it and Insert.

That's it - the page will be included at that point in your Planning page. Whenever Allocating Resources changes, the planning page will also update.

You can see wherever a page in included or linked to in any other pages really easily. Click "What links here" in the "More" toolbox section. That will show you a list of all:

Transclusions - directly used in a page.
Redirects - stub pages that immediately redirect to this page
Links - just a link has been added.

That way, when you edit a page, if this edit fundamentally affects a document that is produced from those linked pages, you can edit those if necessary, perhaps to increment a version or modified date, if these pages are producing a PDF book.

Interwiki

As you know, the Assist systems are based on MediaWiki, then engine that powers Wikimedia.

Each product has its own instance of this, so we have Assist (wiki) instances of (amongst others):

OBS - Calidus HUB
MTS - Calidus TMS
WCS - Calidus WCS
WMS - Calidus WMS 3pl
Portal - Calidus Portal (all types)
MCS - Calidus MCS

In the interests of reducing duplication and possible out of date guides existing within other pages, each of these Assists can use pages out of the other Assists by using a defined interwiki reference.

What that means is you can link to or transclude ANY page from any other Assist, like you would for any page on your Assist.

So, the interwiki shortcuts are:

Calidus HUB - "obs"
Calidus TMS - "ctms"
Calidus WCS - "cwcs"
Calidus WMS 3pl - "cwms"
Calidus Portal - "cportal"
Calidus MCS - "cmcs"

Essentially, you use the Interwiki prefix before the page or template you want to use.

To use a template from another wiki, the syntax is {{iw:TemplateName}}.
To link to a page from another wiki, the syntax is [[iw:PageName]].
To transclude a page from another wiki, the syntax is {{:iw:PageName}}.
To use an interwiki link for a DocLink, the syntax is {{DocLink|:iw:PageName}}.

As mentioned above, Glossaries for all systems are maintained within the Calidus HUB Assist. The page exists in the local wiki, but it transcludes the Calidus HUB version. So, you can continue to use the template {{WMS Glossary}} as normal. But you could also use {{obs:WMS Glossary}} instead and get the same result.

Best use cases for Interwiki functionality are:

Repetitively-maintained and used data, for example Glossaries.
Technical guides linking to customer-facing guides, for example on this wiki CTMS Paragon Interface, where the customer-facing guide maintained in the CTMS Assist is both linked to and transcluded.
Product-specific pages linking to technical specs, for example, in WMS, you would find PoD Guide, which links to the Port of Dover SDD on this Assist SDD 350229 Port of Dover Solution Design as a DocLink to download the PDF i.e. {{DocLink|obs:SDD 350229 Port of Dover Solution Design}}

In this way, we further promote the "write once, write everywhere" mentality and reduce effort, which providing a more connected, more up to date documentation set to our customers.

Saving your Changes

Each change you make, however small, is included in the document's history. To ensure that these comments are not included, you should mark the change as minor when saving your changes. However, this should not be marked as minor if the edit fundamentally changes the document.

Comments should be added whenever saving edits. If you have edited a section directly, rather than the whole document, a comment will already be entered for you. You can leave this there, replace with a new comment or add your comment after this one.

Your comments should reflect the changes. It's good practice to reference any call numbers or system versions associated to the change of you know them. Avoid client names if you can - remember this is standard documentation! For example, for a SalesForce or DevOps change 123465 for customer ABC Travel, adding a new Customer Ref field to a screen, consider entering your comment as follows:

Added new Customer Ref field (123456)

As documentation should always be updated when software patches or releases are made available or released to a customer system, then consider using the ER/patch/release number in the comment, for example:

ER CTMS 047-101 - Added (some functionality) to the screen

When a document is going to be changed to a new version, you should change the version and date within the document, and add the version number to the start of the comment. For example:

v0.02 - Draft issue for review
v1.00 - Ready for Issue.

How this works is slightly different for each editor.

For Source Editing:

Enter a summary comment.
Check whether this is a Minor edit.
Optionally you can Watch this page - if anyone edits it in the future, you'll get an email. You can manage your watchlist from user preferences accessed from your user name.

Once you have selected, you can do the following:

Save changes - if you haven't entered a summary comment you will be reminded, or the changes will just be saved.
Show preview - as you are probably using realtime previews, probably not required. If you do use it, the changes will be shown on the top of the page, but remember your changes have not yet been saved - use the Save changes button as above to commit them.
Show changes - show all changes in text differences showing each line changed, added or modified in a list. Remember your changes have not yet been saved - use the Save changes button as above to commit them.

From Visual Editing:

Click Save Changes
You will be shown a popup - enter your summary here.
Check whether this is a Minor edit.
Optionally you can Watch this page - if anyone edits it in the future, you'll get an email. You can manage your watchlist from user preferences accessed from your user name.

You then have options.

Save changes - if you haven't entered a summary comment you will be reminded, or the changes will just be saved.
Review your changes - show all changes in differences. The changes will be shown in Visual ode with colour highlighting - you can switch to the text differences above as well if that suits you better. Remember your changes have not yet been saved - use the Save changes button as above to commit them.

Some Final Notes

Note:

When creating a new document, you should ensure that the Category tags are added relevant to that document type and client. This allows for easy searching of documents. See the following section on Categories.
A document should be checked that it exports to PDF correctly - in most cases, documents will export with no issues. However, it has been known that a document does not correctly format into PDF. If this is the case, the document should be referred to the Assist maintainer for checking. Documents can be exported to PDF from the toolbar.

Issuing Documents to a Client

Documents should be issued in PDF form.
The document title should follow the standard document template, with a version number, so:
- EST 123456 CUSTREF Title v1.0.pdf
If you use the standard document template with the Doc_Title title page and you specify a version, when you download the PDF, the document will be appended with the version number automatically.
Whilst the Assist system is being adopted, these documents should be held in the standard development or project document folder - please consult your project or product documentation for details.

Anonymous

Search

Assist Editing Guide

Namespaces

More

Page actions

Contents

General

Document Editing

Source Editing

Visual Editing

Standards

Images

Templates

Transcluding

Interwiki

Categories

Saving your Changes

Some Final Notes

Issuing Documents to a Client

Navigation

Navigation

Translate

Wiki tools

Wiki tools

Anonymous

Search

Assist Editing Guide

General

Document Editing

Source Editing

Visual Editing

Standards

Images

Templates

Transcluding

Interwiki

Categories

Saving your Changes

Some Final Notes

Issuing Documents to a Client

Navigation

Wiki tools

Page tools

Categories