About the CAE for KMS contributions

Important:
The CAE environment will be shut down in fall 2024 as part of the IU Knowledge Base transition to the ServiceNow platform. To submit comments or proposed revisions, you can always email the KM team at kb@iu.edu.

On this page:


Overview

Notes:
  • The instructions here assume you are a KB content owner with a KMS account; if you have questions, contact the KM team at kb@iu.edu.
  • When you're off campus, you'll need to log into the VPN.

The Contributor Authoring Environment (CAE) is a set of tools content owners can use to submit proposed changes to existing content in the KMS (Knowledge Management System) repository, and to propose new content. The CAE uses the open-source CKEditor to display copies of KMS content, and gains additional functionality from some third-party CKEditor plug-ins.

After you've submitted your proposed contribution to the KM team, they'll work on it in source, contacting you if they have questions, and then will publish it to the appropriate production endpoint (the Knowledge Base and/or other endpoints you designate).

Propose new or revised content

  1. To get to the CAE editing interface:
    • From the CAE Dashboard (default view): Select the + icon next to the column filters.
      • New: To start a new draft, choose New document. Give it a title, and choose Submit.

        When you create a new draft, you have the option to mark it "Private", making it visible only to you and to the KM team, thus ensuring security for potentially sensitive content. The KM team will designate the appropriate audience(s) you request to maintain this security in production.

      • Revision: To initiate a revision to existing content, choose Update existing document. Enter the appropriate docid, and then select Submit.
    • If you're already viewing a document in the KMS: Choose Propose edit (the "Propose edit" icon). You'll then be prompted to continue your proposed revision in the CAE.
    • If you're already viewing a document in the KB: Choose KB pencil icon to propose content change (the pencil icon). You'll then be prompted to continue your proposed revision in the CAE.
    Note:
    If you attempt to pull in content that is already being worked on in the CAE, you will instead be taken to the existing contribution there; this is to prevent duplicate or conflicting work by multiple users. Also, in this case the text that appear in the CAE will match the KMS version at the time the other person pulled it into the CAE, which may in some cases be different from the current KMS version and/or the live production version in the KB or other endpoints. Submitting your changes will submit any changes made by the person who pulled the document into the CAE, as well.
  2. Once you get to the editing screen, in the upper right, you'll see the content's lock status. To lock and begin editing, choose Edit (or Steal lock, but of course do this sparingly!).
  3. Make your proposed changes. Be sure to consult the following section for hints and cautions.
  4. When you're finished editing, choose Release lock. To mark the content for action by the KM team in the source repository, on the Workflow tab, choose Submit or, if you have approval rights for that content's owner group, choose Approve. If your revisions should wait to go live at a later time, indicate that (with the date, if known) in the comments pane.

After the KM team has worked on your contribution in the source repository and published it to production, it will be removed from the CAE dashboard and you'll receive email notification.

If you decide that your contribution is not needed, or if you submit it to the KM team another way, please remove your contribution from the CAE. Choose the trash can icon on the Contributions Dashboard, or select Delete from the editing screen. Once a contribution is deleted, it cannot be recovered. For existing documents, this only deletes the proposed CAE edit, since it is a copy; it doesn't affect the live document in the KB or other endpoints, or in the KMS.

Note:
To keep the CAE manageable, the KM team will regularly remove old, unworked items.

Things to know while working on content

Very important:
Like most web editors, the CAE is not the best for substantial changes to large or complicated docs; proposed edits to tables, lists, or other types of formatting become nearly impossible for KM staff to interpret. For such needs, email kb@iu.edu.
  • Beware of using Ctrl-z more than once: This is an issue with most open-source editors, and this one is no exception. Refrain so that you don't lose or corrupt your work.
  • If changes aren't being tracked (highlighted in green): Please indicate that in some way (for example, "NEW SECTION HERE") so your changes aren't missed!
  • Formatting: Use the toolbar in the rich-text editor to indicate basic formatting, such as bold text or bulleted lists. Focus on the needed information rather than how things look; KM staff will structure the content in source. Anytime you need to clarify your intent, you can leave a comment, as described below, or indicate your intent within the text itself; for instance, if you begin a paragraph with "Note:", the KM team will typically make it a note panel.
  • Comments: To leave comments in a doc, use the Comments sidetab Image of the comments sidetab on the right. Note that any user can edit or delete another user's comments. Also, comments do not carry over to a document's next round of CAE work, but after the KM team marks a document as completed (the team has finished the work in source), you can view the comments for that CAE version by selecting the Completed button from the CAE dashboard and searching for it.
  • Images: You cannot add images to a document with the "Image" tool. Submit images to accompany a CAE draft or revision in one of the following ways:
    • Send attachments to the KM team at kb@iu.edu. (This action will generate a KM ServiceNow ticket). If you do this, be sure to indicate in your email message that the text revisions are in the CAE; then, within the CAE, note that images will be coming into ServiceNow, so that whoever takes the revision knows to check in the other place.
    • Use some existing file upload option, such as one of the services described in Options for storing files at IU, and include the URL of the file in the comments pane in the CAE (or in the text itself), indicating clearly where the image is to go.
  • Track changes: To toggle tracked changes on and off, select the tracked changes icon.

    Track changes icon

  • Sidetabs: Sidetabs allow you to view a document's metadata, title(s), and any references ("Related documents" in the KB). If you'd like to suggest changes to titles, references, audiences, etc., you may indicate that in the comments, or by simply adding a note anywhere in the text indicating your suggestion.
  • Internal content: You may see one or more lines in certain documents saying "You do not have permission to view this section." This indicates content that is restricted to an audience you are not part of; for example, for Support Center staff, KM staff, etc. If you think that your edits might be relevant to an internal section, ask in the comments sidepane, or contact a KM staff member.
  • Staged content: The KM team often prepares and stages content for later publication; such docs will have text, or blocks of text, surrounded by green and/or red lines. Green surrounds what is currently live in the production KB and will be removed at a future time, and red surrounds what will be added in the future. For example, this is a screenshot of boiler text that was staged for Two-Step Login (Duo) changes:
  • Report bugs: Contact us at kb@iu.edu to report any problems you find. Because the CAE is built on outside tools, some bugs may be outside our ability to fully address. But do let us know about them anyway!
  • On any KMS page, from the Dashboards menu, choosing Contributions takes you to the Contributions Dashboard.
  • While on a KMS document page (kms.iu.edu/d/xxxx), you'll see two icons on the upper right:
    • Select Propose edit (Propose edit) to work on a proposed revision for that document.
    • Select Contribution Dashboard to go to the Contributions Dashboard.

The Contributions Dashboard

On the Contributions Dashboard (the default CAE view), you can enable filters to show new, updated, or completed documents, or only your contributions or everyone's:

  • Select a username to show just that user's documents. (The username reflects who started the document in the CAE.)
  • Use the arrows above the columns to sort; type in the fields at the top of the columns for more filtering.
  • To view CAE contributions that have been marked as completed, choose the Completed button and search by document ID.

New documents will have "draft" in the "Doc" field; others will have their four-letter document ID (docid).

Give feedback

We're eager to hear from you! Send CAE feedback to kb@iu.edu.

This is document kmsc in the Knowledge Base.
Last modified on 2024-06-11 14:47:52.