Follow these recommended steps to migrate your content quickly while minimizing downtime and broken links. Using the new template features, you can also make your pages more findable and easier to read.

Jump to a section...

• What's the knowledge base?
• Knowledge base launch dates
• What does this mean for editors?
• Content eligibility guidelines
• Wagtail training and access
• Edit and recreate your pages
• Publish your new pages
• What's next?

What it is, why it's being built, and how it can help:

Portal’s new knowledge base (or KB for short) is a new hub for self-service technical documentation for the entire CCA community.

Essentially, the KB allows users to find technology help more easily, without having to sift through a multitude of other pages on the site.

KB articles can be classified or “tagged” according to several attributes, namely Primary Audience, Topic, and Platform. A particular article may have multiple Primary Audiences or Topics to which it belongs.

This classification system underlies the KB search function, through which articles may be found using a variety of search parameters.

For example, a student looking for help installing Adobe Creative Cloud software might type install adobe into the KB search, then select both the “Student” and “Creative Software” filters to find the instructions they need.

A staff member may be able to find that same article by searching photoshop with the “Staff” and “Adobe Creative Cloud” filters selected.

Here's a preview of what we're building:

We hope to have a significant amount of content published and available for when the KB launches to all users. To provide time for content creation and migration, the knowledge base launch is split into two phases:

Soft Launch: Tuesday, April 12, 2022

After this date, the knowledge base becomes available to contributing editors to start moving/creating content.

Official Launch: Tuesday, May 10, 2022

After this date, all Portal users have access to the knowledge base.

What you can start now:

Review this guide, and start thinking about the content you want to move or create in the knowledge base. Not all content belongs in the knowledge base, so make sure to follow the eligibility “checklist” below before preparing to move or create pages within the KB.

If you'd like, start reviewing your content for necessary updates. If you're unsure where to begin, check out our tips for editing your pages for the knowledge base.

You can also help us by submitting Topic and Platform tags you'd like to be available for the knowledge base. Read more about tag list submissions here.

What you can start in April:

Eligible content will need to be (re)built in the Portal knowledge base using the new “How-to” page template. You'll be able to start this work after the soft launch in April.

There's no requirement to do this work nor a deadline to complete it, but Portal users will be able to access the knowledge base after the official launch in May. Try to publish your pages by then!

Why existing pages need to be rebuilt:

Current Portal page templates don’t include the same data structure and features that we’ve built into the “How-to” page template, which is why content migration is a central part of the KB launch.

While recreating pages takes time, editors are primary beneficiaries of the new knowledge base, which eliminates the need to organize documentation within the site hierarchy and makes it easier to share content across user groups and in multiple ways.

Starting out with "How-to" Guides

The knowledge base doesn’t yet include all self-service technical documentation. In order to release the KB sooner and reduce the immediate content work for editors, we have focused on one specific knowledge format for the initial release: step-by-step instructions, or “how-to” content.

“How-to” pages make up the majority of Portal’s technical documentation, which is why it’s the first available page template for the KB.

Focus on end-user documentation

Technical documentation is typically written either as:

• End-user documentation, instructions for the customer using the service, platform, or tool; OR
• Internal documentation, written for those administering the service, platform, or tool.

The Portal knowledge base is designed to host end-user documentation primarily. Internal documentation can be built/stored elsewhere (such as a Google site) and shared amongst system administrators as needed.

What about other types of documentation?

We also understand that a lot of technology help doesn’t fit a step-by-step format, but we ask you not to use the “how-to” page template for other things, like announcements or policies.

In the near future, we plan to create format-specific page templates for other types of technology help, such as tips and general info, software overviews, troubleshooting steps, and more.

Content Eligibility Checklist

Knowledge base articles for the 2022 Q1 release should meet all of the following criteria:

Knowledge Base or Workday Learning?

CCA launched Workday Learning, our employee training platform, in Fall 2021. The Workday Learning library includes both required training programs and professional development courses.

In some cases, content you think should move to the Portal knowledge base may be better suited for a Workday Learning course. As a rule, Workday Learning is best for in-depth training, while the knowledge base is designed for documentation.

If information needs to be referenced frequently or periodically, it probably belongs in the knowledge base.

If information can best be learned all at once, as a primer or a course, you may want to consider Workday Learning instead.

In some cases there’s overlap, and you may want to include knowledge base documentation as a lesson or resource within a Workday Learning course.

Reach out to Human Resources for more information on accessing Workday Learning.

Getting started

First, you’ll need to familiarize yourself with the KB tools in Wagtail, Portal’s content management system.

1. Request access to the knowledge base via Help Desk, providing a brief description of the content you’d like to add. Skip this step if you've already been contacted by the Portal team about contributing to the knowledge base.
2. Upon approval of your request, complete the required training course.
3. You’ll receive full access to the knowledge base tools in Wagtail upon completion of the training. Reach out to Help Desk if you are not granted access within two days of completing the training.
4. As you start to create KB articles, reference our Wagtail Guide for Knowledge Base Content as needed.

Managing editing access

The Portal knowledge base simplifies the process of creating documentation by organizing it all in one place within Wagtail. However, because the knowledge base is shared by many editors, you can organize your content within the Knowledge Base section in Wagtail using Knowledge Base Folders.

These folders will help us segment permissions within the Knowledge Base Wagtail section. By default, any "general" knowledge base article is editable by all other KB editors.

If you create a KB folder, other editors will be able to add their own content within it, but they won't be able to edit your articles there unless you give them explicit permission to do so.

Though you'll be the "owner" of any KB folder you create, you won't be able to edit others' pages that get added within it (and the same applies for when you're adding articles in others' folders as well).

If you'd like to set up yourself or others with full editing access to one or more of your KB folders, reach out to Help Desk with the following:

1. The KB folder(s) you'd like to share
2. The editors who should have access
3. Any other special requests/instructions

Additional editors can be added as needed.

Review your current content

Review your existing pages for compatibility with the new “how-to” template.

If your page is already in step-by-step format, it should be possible to copy and paste most content from the original page to the new one.

Now is a good time to think about improvements, however:

• Simplify your steps: cut unnecessary words and details, and use simple language. It’s okay to have sub-steps, but keep them to a minimum!
• Use subheadings to split your page up into sections, especially if your instructions involve several sub-processes or phases. Doing so makes a complex page easier to parse.
• Add, update, or cut images. A few tips about images:
  1. Images are not a substitute for text, they are merely supplementary.
  2. Images should enrich the content, so prioritize images that help illuminate complex steps. You probably don’t need an image for every step!
  3. Annotate your images to highlight specific components, like an arrow pointing to the button described in the step.
  4. Update your images or else cut them entirely! The same goes for pixelated images.
  5. Resize your images appropriately so they don’t take up too much (or little) space on the page. You can resize image files before uploading them to Wagtail, using Apple’s image Preview.
  6. Rename your images so they are easier to find in Wagtail's image picker. With over 10,000 uploaded images, more specific titles can save you a lot of time and headache.

• Use sidebar links sparingly. The more links you add, the less visible each one becomes. Prioritize linking to important supplementary resources.
• Use the Body blocks that best fit your content. Besides step blocks and subheadings, other content blocks may benefit your particular content, such as a Panopto video or a note.

Edit your content

Depending on your editing preferences and content needs, follow one of our recommended editorial workflows:

When your new pages are ready-to-go, you’re free to publish them. To help ensure a smooth transition to your new pages, consider the following best practices:

Inform your users

Before launching your new page, communicate upcoming changes from your old page. Put a note at the top of your old page along the lines of:

After you launch your new page, update the note to include the link to your new page and a date for deprecating the old version:

Your old page shouldn’t linger too long after the new page launches. If you choose to keep it around for a while, make sure to remove any inaccurate information. You don’t want folks to following outdated instructions!

Inform your stakeholders

You may also need to inform other colleagues/peers about changes to your pages. Consider those who might be affected by these changes, and make sure they know what’s happening!

Fellow editors, fellow system administrators, and supervisors responsible for the content are a few examples of stakeholders to notify.

Also consider those who reference your page, who may need to update links or communicate such changes to their stakeholders.

We’ve prepared a shared KB Migration Tracker for documenting/announcing page migrations for the KB launch, which we hope simplifies the change management process for you and your stakeholders!

Replace links to your old content

Make sure to update the other pages you edit so any links pointing to your old page will now point to the new one.

We’ve implemented a broken link checker for this project, which should help you and other editors manage links affected by the KB launch.

Request redirects if needed

Link updates are preferable, but our team can also set up redirects if you want your old page’s URL to point to the new page automatically.

Typically, redirects are appropriate for pages that are widely shared, especially on other channels or sites (such as in email or on a Moodle site).

Request redirect support here. The redirect will only function once the old page has been unpublished and the new one published.

The content migration timeline will look a little different for everyone, depending on things like editors’ availability when the knowledge base launches and the amount of content they wish to move.

The Portal Team will remain available for access, training, and content support following the phased KB launch. You can continue to use this guide as a reference as needed.

We also need to hear your feedback about what we’ve built! What do you like about the knowledge base? What’s missing or could use improvement?

Please send requests for new Topics or Platforms via Help Desk.