Style Guide Community Project

[thatblindgeye]

Title	Author	Date
Style Guide Community Project	Eric Olkowski	2/7/2022

Style Guide Community Project

Summary

The purpose of this idea is to bring in members of the TOP community and give them the chance to contribute to open source by having them help update our lessons to align with the updated style guide.

Motivation

There are a lot of inconsistencies and less than ideal practices throughout the many lessons we have. This includes verbiage for universal sections (Learning Outcomes), section placement (Additional Resources/Knowledge Checks), link names, and so on.

While the main content of a lesson should be more in the author's voice, there are some things that either must be consistent, or would create familiarity for users by being consistent.

Suggested implementation

With the updated style guide approved, the plan is to tackle lessons by path/course, so there will be several stages. For example, Foundations would be one stage, while the JavaScript course in both full stack paths would be anohter stage.

Not everything would be updated at once. The verbiage for the new Lesson Overview section (replacing Learning Outcomes) as well as Knowledge Checks would either be a future stage of this project, or it would be a completely separate project.

The following items of the layout style guide are currently planned to be fixed as part of this project:

• Lesson layout
  • Order of the sections, e.g. Knowledge Check comes before Additional Resources, as well as any universal verbiage
  • Lesson/Project has a proper Introduction, and the main content of the lesson isn't included in the Introduction (main content should come after Lesson Overview)
  • Learning Outcomes in existing lessons are updated to Lesson Overviews (the actual Lesson Overview items should not be updated as part of this update)
  • Assignment sections are wrapped inside the <div> element included in the style guide, and only include resources that users should read/watch (any resources necessary for completion/understanding of the lesson must be placed here, not sprinkled throughout the lesson)
  • Practice sections are wrapped inside the <div> element included in the style guide, and any warm-up/practice material a user is meant to do must be included here, not sprinkled throughout the lesson)
  • Knowledge Checks are all wrapped in the <a> element included in the style guide, and only link to resources/content already mentioned in the lesson (the actual Knowledge Check items should not be updated to align with the descrption of Knowledge Checks included in the style guide)
  • Additional Resources include the default bullet item if the lesson doesn't have any yet (otherwise the default bullet item should be removed), and this section is the last section of any lesson
• Project layout
  • Assignment sections are wrapped inside the <div> element included in the style guide, and any optional/extra credit instructions are placed in appropriate Extra Credit section (the actual project instructions should not be updated as part of this update)
• Headings use the Title Case mentioned in the style guide, sub-heading syntax is correct (e.g. if the sub-heading isn't meant to be inline, it uses the #### syntax, otherwise it should use the Markdown bold **text** syntax)
• Lists are appropriately used/numbered, e.g. no numbers are skipped in numbered lists, indentation is correct, etc.
• Codeblocks have the language declared in the Markdown file
• Links and Image alt text have proper and descriptive names (e.g. links don't have text that just says "click here" or "this article"), and links meant to be read as part of lesson completion aren't sprinkled throughout the lesson
• Codepen embeds are from The Odin Project account (only a maintainer can updated these so the user would simply have to note any non-TOP Codepens)

Drawbacks

The biggest drawback would be community members getting in over their head or not following instructions/the style guide correctly, leading to double the work on my part to "clean up" or tell users how to fix any issues.

Alternatives

Keep the work for maintainers only to do, but I don't believe this is a viable alternative nor would it be as beneficial an option as opening this up to the community.

Additional

Completed

• Foundations Path
• Intermediate HTML and CSS Course
• Advanced HTML and CSS Course
• Ruby Programming Course
• Ruby on Rails Course
• Database Course
• JavaScript Course
• NodeJS Course
• Getting Hired Course