Use the CAE for KMS contributions

Note:

The instructions here assume you are a KB content owner with a KMS account; if you have questions, contact the KM team.

On this page:


Overview

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): Click the + icon next to the column filters.
      • New: To start a new draft, click New document. Give it a title, and click 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, click Update existing document. Enter the appropriate docid and click Submit.
    • If you're already viewing a document in the KMS: Click 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: Click See an image depicting what was just described (a125g) (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 it there; this is to prevent duplicate or conflicting work by multiple users. Also, in this case the text that is pulled into the CAE will match the current KMS version, which may in some cases be different from the live production version, if the KM team has made changes which are not yet published.
  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, click 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, click Release lock. To mark the content for action by the KM team in the source repository, on the Workflow tab, click Submit or, if you have approval rights for that content's owner group, click 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. Click the trash can icon on the Contributions Dashboard, or click 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 (e.g., "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. Currently, 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 (i.e., the team has finished the work in source), you can view the comments for that CAE version by clicking the Completed button from the CAE dashboard and searching for it.
  • Images: You currently 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:
    • Use some existing file upload option, such as Box or Slashtmp, 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.
    • Send attachments to the KM team. (This action will generate a FootPrints ticket in the KM workspace). 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 FootPrints, so that whoever takes the revision knows to check in the other place.
  • Track changes: To toggle tracked changes on and off, click 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, e.g., 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 Duo changes:
  • Report bugs: Contact us 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, clicking 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:
    • Click Propose edit (Propose edit) to work on a proposed revision for that doc.
    • Click 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:

  • Click 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, click 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.

This is document kmsc in the Knowledge Base.
Last modified on 2019-04-23 16:47:53.

Contact us

For help or to comment, email the UITS Support Center.