Site Style Guide

style guide for site

Site Style Guide

This document outlines the best practices and formatting/styling standards for the KnowledgeBase.

Creating New Documents

The following are guidelines for the creation of new documents in the KnowledgeBase.

  1. Log into the Knowledge Base Admin Tool — https://kb.wisc.edu/kbAdmin
  2. Select the Documents tab.
  3. Select New Doc.
  4. From the Template drop-down menu, select the appropriate template. There are currently, two templates:
    1. PD Group Template - used by PD staff for creating content.
    2. Open Education Template - used by the OER group to create content.
    3. Enhancing Online Education Template - used by the EOE Group for event content
  5. Your new document will be created using the site's CSS file (remote.css). Content added will be formatted using the CSS file on the screen. It may look slightly different when viewing the live document outside the KB Admin environment. 
  6. The document will show some placeholder text that you can delete.

Naming and Describing Your Document

  1. Provide a descriptive name for the document without making it too long. The KnowledgeBase searches on any word in the title or keywords added to the document.
  2. Provide as many keywords as you can think of to help people find the document you are creating. Consider any common misspellings or other phrases people might use to search for this content.
  3. The Summary box is where you can describe the purpose of the document. This is better than a long document title. In writing your summary statement, consider the intent, audience, focus, and desired outcomes of the document.
  4. The Page Header box is where you can insert a custom header that will appear that notifies users that this document is part of a larger collection of KB documents. This is helpful to address the fact that the Topic Map will NOT appear in a KB document if it is accessed from outside the CTLM KB site (ex. through campus KB search). Note: the Open Education Template and Enhancing Online Education Template already assigned the appropriate header to documents.

Images

If you are adding images to a document, you should place those documents using the shared attachment folder link in the Attachment section. The format of the image should be a PNG file, if possible.

  1. If you haven't yet done so, click the Save Change button. 
  2. Click on the Create doc XXXXXX attachment folder link in the Attachment section.
  3. Click OK to create the folder. The new attachment folder is displayed.
  4. Click Choose Files button and select the file you want to add to the document. Click the Upload button to add the image to the folder. Click Close.
  5. Place the cursor where you want to add the image and click the Place image link in the attachment section.
  6. Click on the image. The Image Options window appears below.
    image options
  7. Click on the Alternate Text (T) image. Add a description of the image and click Update.

Headings

Headings should be formatted using <h2> tag or <h3> and <h4> tags for subheadings. Make sure you use headings in the appropriate descending order (h2, h3, h4) (not h2, h4).

Technology References

  • As a general rule, try to leverage and embed existing technical documentation using the Custom KB include doc or Custom KB link doc features into your document instead of creating new and duplicate documentation.
  • Use the Custom KB Link Doc tool to create links to other KB docs, instead of hard-coding them. 
  • When writing documentation and reference technologies, they should be in bold to highlight their use and make it easy for a user to identify.
    Example: Send students to a shared Google Doc to work on the assignment. If you reference specific tools in your document, make sure you select that tool in the Technical Documentation topic list.

Command and Menu Choices

  • When referencing a menu choice, use bold
    Example: From the Edit menu...
  • When Referencing a path or series of menu choices, separate them with the | symbol (not in bold).
    Example: Select Edit | Options | Color and ...
  • Use "select" and not "click" or "press" to describe interactions with menus and links.
  • Use "log in" and not "log on" or "login"
  • When referencing wording or options, use bold and italics
    Example: From the Edit menu, select Keep student attributes anonymous.
  • Use the text formatting provided by the tool, regardless of whether it violates our guide.

General Style Issues

  • Use APA style in bibliographies. Visit Purdue APA Style Resources for guidance.
  • Use the present tense and active voice in documents whenever possible.
  • Use gender-neutral pronouns.
  • Use the familiar "you" reference instead of the formal "user" reference.
  • Use the following to describe roles: Student, Instructor, Teaching Assistant

Tables

Tables should be formatting in a standard way to represent tabular data, not as a formatting tool. Headers of tables should use the <TH> tag. This will be represented through CSS as light gray and bold. The accessibility checker will flag tables not formatted correctly

Example:

Table Caption
Element (header cell with column scope) Heading 1 (header cell with column scope) Heading 1 (header cell with column scope)
Element 1 (header cell with row scope) yes no
Element 2 header cell with row scope) no no

Assigning Topics

In the Topics section, select from the available subject areas identified in the KnowledgeBase. If you are creating new content that does not fit within the existing topic framework, contact the Administrators (Julie Collins, Timmo Dugdale, Cid Freitag), and they will facilitate the creation of the necessary topics. In addition to keyword searching, users can leverage the topic menu if they go to the KnowledgeBase or as they view documents they were directed to from other sites. Note 1: Users, however, who find documents through the main KB site WILL NOT see the Topic Map at the top of the documents. Note 2: Documents created using the Open Education Template should already have the Open Education main topic selected. Select any additional subheadings under that main topic, and/or any other topics that are appropriate for the document.

Currently, the main topics to which content is being added are:

  • General Guidance: Basic information or guidance on teaching.
  • Active Learning: Methods and guidance on the design and delivery of active learning approaches.
  • Course Design: Documents dealing with any element of the course design process.
  • Course Evaluation: Methods and approaches for gathering data and feedback on a course.
  • Equity and Inclusion: Resources that address elements and approaches related to diversity, equity, and inclusion.
  • Events: Documents related to CTLM events
  • Discussions: Methods and guidance on the design and delivery of synchronous and asynchronous discussions.
  • Group Work: Methods and guidance on the design and delivery of collaborative group work.
  • Informed Design: Course design that is based on feedback from users, analytics, and instructor reflection
  • Lab Courses: Documents related to issues faced by instructors of lab courses.
  • Large Courses: Documents related to issues faced by instructors of large enrollment courses.
  • Open Education: Methods and approaches related to the creation and distribution of open educational resources.
  • Student Assessment and Feedback: Methods and approaches related to assessing students and providing feedback on performance.
  • Student Engagement: Methods and approaches for facilitating student/student and/or student-instructor activities and interactions.
  • Team Teaching: Addressing issues related to the design and delivery of courses in a team teaching environment.
  • Technical Documentation: Designation of this topic is used for any document that references the use of specific technologies. In the creation of a document, tag the specific technology being used. Referenced technologies should be formally supported by campus. If you are creating new content that references a new technology, contact the Administrators (Julie Collins, Timmo Dugdale, Cid Freitag), and they will facilitate the creation of the necessary designations.
  • Writing: Methods and approaches to facilitating writing within a course.

SeeAlso References

Along with any other relevant documents you want to be referenced below in the See Also section, add a SeeAlso Reference to each topic homepage you identify.

  • General Guidance: 104614
  • Active Learning: 104462
  • Course Design: 113053
  • Course Evaluation: 113051
  • Discussions: 103895
  • Equity and Inclusion: 105784
  • Events: 104612
  • Group Work: 104612
  • Informed Design: Not active yet
  • Lab Courses: 114235
  • Large Courses: 105171
  • Open Education: 119887
  • Student Assessment and Feedback: 113332
  • Student Engagement: 107448
  • Team Teaching: 116449
  • Technical Documentation: 104615
  • Writing: 119856

Saving Document in Draft

If you are still working on a document, click the In Process radio button from the Status section. (Note: you may first need to click the Save or Save Change button directly below the text entry window before you can submit the document to In Process status.

Submitting Documents

When a document is ready to be published, select the In Review (awaiting activation) radio button from the Status section. Then select Submit. OER Group members can publish documents that are tagged with the Open Resources topic. Select Publish from the Status section. 




Keywords:CTLM style guide   Doc ID:104933
Owner:Timmo D.Group:Center for Teaching, Learning & Mentoring
Created:2020-08-13 15:35 CDTUpdated:2022-08-18 14:46 CDT
Sites:Center for Teaching, Learning & Mentoring
Feedback:  0   0