Skip to content

Documentation Standards

Description and Purpose

A quick way to address curriculum gaps and add more context to our existing content is through integrating external content into our curriculum. Linking to documentation exposes learners to resources that are integral to their learning journey. The content item in Author is called External Resource.

Content Location

Documentation is placed within a module, at the end of Introduction to New Material (lessons, articles), but before practice and assessments (projects, quizzes).

Overarching Standards

Fields in Author

Content

Description

The description provides a brief (1-2 sentence) description of the contents of the documentation.

  • The description should include key terms when appropriate (for SEO purposes).
  • The description should be written in sentence case.

Source Data

Source Name

This is the name of the documentation and the section (if applicable) that the learner is reading.

  • This is surfaced as the text of the link when rendered.
  • Example: GitHub Guides
Resource URL

This is the link we are pointing learners to.

Body

This field provides a brief description for the purpose of the documentation and why it is useful.

  • The body field follows the following template:
In this documentation, you will learn [WHAT THEY WILL LEARN]. This is helpful if [WHY THEY SHOULD LOOK AT IT]. 
  • The reasoning should tie into the larger objectives of the module, track, and career path.
  • The body should explain how the documentation relates to previous topics they already learned and describes how the content differs from previous content on the same subject.
  • (If relevant) It describes how this particular article is noteworthy in terms of the content and/or presentation.
  • The body should not exceed 300 characters.

Attributes

Title

The title of the documentation.

  • The title is displayed to learners at the top of the narrative in the LE and in the course menu.
  • Titles should include key terms when appropriate (for SEO purposes).

Slug

The slug is used to create a URL for the content item.

  • The slug is auto-generated based on the Title field though it can be edited.
  • Slug will start with ext-doc and then finish with the name of the content
  • Example: ext-doc-github-guides

Minutes to Complete

This field should be how long you think the article and any embedded elements will take to complete.

  • For Documentation, time to complete should be between 10-30 minutes.
  • Most individuals read at around 250 words per minute, so this can be used as a proxy while you estimate time to complete. When in doubt, air on the side of being conservative - so make a longer estimate rather than a shorter one.

Credited Authors

This field allows you to add an associated author(s) to the item. For now, this field is not publicly visible but is helpful as a reference.

Access Control

Curriculum developers use this field to determine whether a Free or Pro audience has access to this item.

Linked Content

Learning Standards

Documentation has the ability to be linked to learning standards. This may be done when a learning standard is about the documentation.

Containers That Use This External Resource

This field is auto-generated and will populate any containers that contain this content item.

Examples