Getting started – Guardrails

The advice here is listed A-Z by subject area.

Compassion

• Do be compassionate with yourself and others.
• Do ask questions and raise bugs.
• Don’t assume that the development team know about the issue you just found.
• Why? This is all new. It has changed since you last saw it. New features are being rolled out every sprint. It’s a moving picture for us all. Please send queries to David Morris, product owner.

Content set

• Do work in the relevant content set on Sandbox.
  
• Do focus on just the content changes that will be released to the customers who have bought a subscription to that content set.
• Don’t experiment in the release content sets on Sandbox.
• Do experiment in the Experimental content sets on Sandbox, or the app-text version of Chorus.
• Why? Bundles in the release content sets are on the path for release to the customers. Any experimental work done here is at risk of being accidentally released to customers and may break content for them. 

Contractor’s choice and submit proposals

• Don’t add contractor actions into the suggestions lists.
• Don’t delete any automatically added contractor actions suggestions.
• Don’t add your own suggestions to the "Manufacturer", "Supplier" or "Supplied by" rows.
• Why? Contractor action suggestions in the "Manufacturer", "Supplier" or "Supplied by" rows are used by Source Intelligence, to provide ROI stats to our manufacturer customers. This means that:
  • ‘Contractor’s choice’ and ‘Submit proposals’ are automatically added to the suggestion lists for any "Manufacturer", "Supplier" and "Supplied by" rows. 
  • When the content is released to the customers, any manually added contractor actions suggestions are stripped out.

For more information, read the Contractor’s choice and submit proposals support article.

Copy and paste

• Do use the Tx Clear formatting button on the Chorus edit toolbar to remove any inherited formatting from your pasted text.
• Do use Paste as plain text (Ctrl+Shift+V) to remove any inherited formatting from your pasted text.
• Do use the formatting buttons within Chorus to apply formatting in line with the house style guide. 
• Do check your work in both light and dark themes
  
• Why? On Paste(Ctrl+V), font colours and background colours are not stripped. As a result, your content may contain colours that are inconsistent with the house style. This is most obvious when you switch theme, e.g. from light to dark.  Incorrect styles can make text illegible to customers.

Description row

• Do write appropriate guidance against this row. This is in the exemplars.
• Do add a 'Description' row to the top of the CAWS clause, if it is missing and relevant.
• Don’t rename or delete this row.
• Don’t add suggestions to this row.
• Why? 
  • The Description row is used by customers for the summary schedulesfeature.
    • Chorus reads from 'Description' and 'Description:'. Other spelling is not picked up.
    • Chorus does support user-created description rows and multiple 'Description' rows. 
    • If there are multiple, the 'Summary schedule' will show the value (blank or filled) of the top one. If the top one is parked, it will show the value of the next one.
  • The behaviour of suggestions against the Description row may be buggy. 
• For more information, see the authoring guide and glossary.

General guidance - Uniclass

• Do keep your general guidance split into multiple separate parts.
  • For example, general guidance 1.2 should be in a block of its own, not mixed in with part 1.1 or 1.3.
• Don’t merge your general guidance into one large block.
• Why? When we come to provide the feature to link to specific areas of general guidance, we will link into these smaller part blocks.

General guidance - CAWS

• Do keep general and clause guidance in a block for now.
• Don't add new guidance into the individual headings.
• Why? Adding new guidance to the headings results in differing formatting and unaligned ordering. See 'Guidance moving' below.

Guidance links

• Do add new guidance-to-guidance links using the gl: keyboard shortcut and menu. 
• Do edit existing guidance links using the same gl: method. 
• Why? Known limitation. The Add link modal treats guidance links like any other link.

Guidance moving

• For existing CAWS clauses: 
  • Don't move clause row guidance down next to the row titles. 
  • Do add guidance for any new rows into the existing clause guidance block at the top. 
  • Why? When existing guidance moves, the bundle changes preview shows all the text as changed.
    This means the editors and copy-editors lose the detail of any small changes within the moved text.
    It also means the customers get an update notification but cannot see meaningful changes.
    Later, we will add a silent update flag so that we can restructure the clause guidance without spamming the customers. 
• For new clauses: 
  • Do add whole clause guidance next to the clause title at the top of the guidance panel.
  • Do add clause row guidance against row titles. 
  • Why? As the whole clause is new, all text is relevant to editors, copy-editors and customers.
    This means we can have well-structured content from the outset, with no negative effects.

Guidance styles and layout

• Do reapply the example style if it is missing from the guidance edit view. 
• Do apply the appropriate general guidance heading style. 
• Do remove any extra empty paragraph spaces and line breaks.  
• Do rely on the guidance panel preview mode for an accurate representation of how the customers will see the guidance.
• Don’t rely on the change preview or the edit views for an accurate representation of spacing and layout.
• Why? Known limitations. 
  • Any guidance imported from NBS Building had styling applied in a more simplistic way. We’re now able to apply styles in a more structured way that will give us greater control of how the guidance is laid out.
  • The edit mode and the change preview have some layout bugs. These are currently on the backlog as there are higher priority items to address first.  

Lists-as-tables

• Do convert any lists that have been converted into tables back into lists.
• Don’t set a bundle to the Ready for final checks stage until these tables have been converted back into lists.
• Do read the lists-as-tables support article for more information.
• Why? Known limitation: Importing the CAWS data from the classic tools introduced some errors. The development team have fixed all the lists-as-tables where it has been safe to do so. The remaining examples now need to be fixed manually as part of the new Chorus authoring process.

New clauses

• Do create new clauses, with guidance.
• Do create new suggestions lists for rows.

New sections

• Do create new sections, based on the template section.
• Do add library tags for the new section.
• Do add scope and general guidance for the new section. 

Notes

• Do add bundle notes to rows and clauses.
• Why? Bundle notes can help us communicate across the technical team. We can use them to keep a record of any discussions and decisions.

Park/ delete 

• Do park any published rows or clauses that you want to be removed from your section when it is next released to the customers. 
• Do delete any new clauses or rows that you have added into your bundle but no longer wish to release to the customers. 
• Don’t park items for workflow reasons. 
• Why? 
  • In bundles, we need a way for authors to say that they intend for a live clause or row to be deleted from the content, but for that still to be visible to editors and copy-editors. We’ve re-engineered the Park feature to serve this purpose. 
  • If you create a new clause in the bundle and then park it, when the customers receive content updates for this section this clause will not show as deleted. This is because, for the customers, this clause has never existed. 

Reference documents updates

• Do update any out-of-date references.
• Do use the screen check report to list all the reference links in the content of your bundle.

Restructure 

• Don’t restructure a clause, if possible. 
• Why? Known limitation. There is a bug which means the restructure is not being flagged as a content update change to any customers who are already using this clause. 

Save your work

• Do save your work often. There are Save buttons, and you can use the keyboard shortcut Ctrl+S.
• Don’t make lots of edits without saving.
• Why? There is no auto-save. If you are inactive for a length of time, such as over lunch, your licence will be refreshed and you may lose unsaved work.

Spell check

• Don’t accept or reject spelling corrections made by the browser.
• Do leave all spelling correction feedback to the copy editors.
• Why? In earlier tests, we suggested using the Chrome OED language settings. However, it does not give us the accuracy we need. For now, spelling corrections will be flagged by the copy-editors during the proofreading stage.

Stage

• Do change the bundle stage when you are ready to pass your work onto the next person in the process.
• Do change the bundle stage when you are starting your work.
• Don’t do your work with the bundle stage set to someone else’s stage.
• Why? The bundle stages help us see the progress a bundle is making though the process, and who has the current responsibility. When you change stage, Chorus automatically creates a revision for that stage. These revisions can be used to filter the bundle changes list. 

Suggestions

• Do add text suggestions.
• Do add clause link suggestions in Uniclass work section content sets. 
• Do delete obsolete suggestions. 
• Don’t delete the whole insert to delete all suggestions. 
• Why? Known limitation: Chorus does not yet understand that deleting the insert means deleting all the suggestions. If you delete the insert, when the bundle is released, the suggestions will still be released too. 

Support

• Do read the Technical Team support articles.
• Why? In bundles, there are features and processes unique to the Technical Team. The same feature in projects and masters may work differently for the customers.
• Do read the Authoring guide. 
• Why? So you can be consistent as a team and learn from each other’s experiences.
• Do reach out to content and development team members. We’re here to help.
• Don’t make it up as you go along.
• Why? Your content might not work correctly for the customers, and you will have to redo your work.

System requirements

• Do work with any browser, such as Chrome, Edge or Firefox or Safari.
• Do work on a full width screen, such as a laptop or larger.
• Don’t work on small screens, such as a tablet or phone.
• Why? Know restriction: Whilst much of Chorus is responsive, some features are not available or not optimised for smaller screens.

Table styles 

• Don’t apply the header styles to old tables in the Edit table dialog box. These styles are: 
  • Top row as header. 
  • First column as header. 
• Do recreate old tables if you were going to edit them anyway. 
  
• Why? 
  • Known restriction: Whilst new tables are robust, we have a known bug when row or column header styles are added to legacy tables. If we recreate the tables, they will be more robust in future. 
  • If you've already applied table header styles to a legacy table, please recreate the table as new. Known restriction: The new table might look at little strange in the change preview, but it should be fine when we release to the customers. 
  • Know restriction: If this table is in general guidance, the customers won’t receive an update notification. But for this bug, the lack of update plays in our favour as the customers won’t be notified of a low priority formatting change. 

Updates

• Do cross-check with colleagues to ensure you’re not working on the same thing at the same time. 
• Don’t accept updates in your bundle. 
• Do ensure there are no updates in you bundle before going to edit or screen check. 
• Do start your bundle again if there are updates for your bundle. 
• Why? 
  • Known limitation: Updates don’t work in bundles.  
  • The ‘Updates’ tab is visible, and you will see updates in the table, but the updates preview won’t open so you cannot accept the update.  
  • We are shortly going to put in a block to stop you publishing bundles to customers that contain outstanding updates. 

VPN

• Do work without connecting to the VPN, if you wish.
• Why?
  • Unlike the classic tools, Chorus does not require access to the VPN.
  • You may find that Chorus runs quicker when you're not connected to the VPN.