Adapt Wiki Style Guide

[This Style Guide is a draft. It is a work in progress. Perhaps in the future, some form of style guide may be adopted by the Adapt community. This has not been adopted.]

It is not the intent of this style guide to address every situation encountered in writing a wiki. The intention is to bring a modicum of stylistic uniformity across wiki pages, making them easier to comprehend and easier for an open source community to write.

Target Audiences:

• Adapt Framework:
  • the technical user: This is a person who can install the framework and use it to create a course with little or no help from another person; who can utilize input from technical support without it be being formatted as step-by-step directions. This is a person who is capable of using the command line; who has familiarity with GitHub, web servers, JSON, HTML, and CSS; who understands broad concepts of web development even if it is not their forte.
  • the developer: This is a person whose technical skills exceed the technical user's in the areas of programming, testing, and the web stack. They have the skills to create and modify plugins or to contribute to the Adapt codebase with new code or testing.
  • (A case may be made for non-technical users being capable of using the framework after it is installed. Their success is dependent upon the use of JSON and the grunt and adapt CLIs, etc. These are technical skills. Adapt has made the decision to provide the Adapt authoring_tool as an interface for the non-technical user. While some so-called "non-technical" users may benefit from information in the framework wiki, no specific effort will be made in the framework wiki to address the needs of "non-technical" users.)
• Adapt Authoring Tool:
  • the non-technical user: This is a person who would not attempt to use the Adapt framework without the assistance of the authoring tool or without having someone else to install the framework for them and to guide their work.
  • the technical user: This is a person who can install the Adapt framework and use it to create a course with little or no help from another person; who can utilize input from technical support without it be being formatted as step-by-step directions. This is a person who is capable of using the command line; who has familiarity with GitHub, web servers, JSON, HTML, and CSS; who understands broad concepts of web development even if it is not their forte. Anyone who can install the authoring tool is a technical user because, at this point, installation requires one to decide which instructions apply to their type of computer.
  • the developer: This is a person whose technical skills exceed the technical user's in the areas of programming, testing, and the web stack. They have the skills to create and modify plugins or to contribute to the Adapt codebase with new code or testing.

Code:

• Code will be styled with appropriate markdown that indicates code: a tick, a fenced code block, or syntax highlighting.

Command Lines:

• Code that is presented as command lines will not start with a prompt such as $. Including it complicates using the code via copying and pasting, since the $ must be deleted.
• Command lines will start on their own line.
• Command lines will be styled with a tick, a fenced code block, or syntax highlighting.

Links:

• In general, hyperlinks to external resources will not use Git Flavored Markdown (GFM) such as [GitHub](https://github.com). They will instead use the HTML <a> tag with the attribute target="_blank". The rationale is to avoid having secondary content replace primary content and so detract from progress through the wiki page's content. target="_blank" opens the content in another browser window so that primary and secondary content may be read side-by-side. (GFM does not currently support target="_blank". This style rule should be reconsidered if support begins.)

###Words, Phrases, Terminology plug-in: When identifying components, extensions, menus, themes, etc., indeed any code that resembles AMD or CommonJS modules, "plug-in" will be spelled using a hyphen. While English tends to consolidate hyphenated compound words over time, prominent use continues to prefer the hyphen--even in Microsoft's Language Portal.