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.

Brand Name:
The brand is the single word Adapt. It is a registered trademark, but the decision has been made not to follow it with either ® or ™. Explanation follows:

[6/9/15, 7:49:54 AM] Chuck Lorenz: Is "Adapt Learning Framework" the most complete and branded name for it? And, consequently, the best phrase to be using in outward facing materials when introducing the product? Can the same be said for this phrase: "Adapt Learning Authoring Tool"?
[6/9/15, 7:50:05 AM] Chuck Lorenz: My context, of course, involves READMEs and wikis. I'd prefer to begin articles with the full "brand" name even if I use more simple references later on.
[6/9/15, 7:52:38 AM] Sven Laux: Hi Chuck, thanks for pointing that out and raising it. Interestingly, I have been making every effort to remove "Learning" wherever possible. This is because we have registered the trademark for "Adapt" (i.e. without the Learning part) and want/need to build the brand around that - so that we can protect it as the project. I'll have a word with Matt to explain this.
[6/9/15, 7:53:36 AM] Sven Laux: In other words, we should be referring to ourselves as "Adapt team/project/framework/etc" without the "Learning" part.
[6/9/15, 7:55:20 AM] Chuck Lorenz: Is there something we should be doing in our wiki articles that would support and validate the trademark claim?
[6/9/15, 8:00:26 AM] Sven Laux: I have taken some advice on this from specialists and the result is that I have decided not to add the (R) or (TM) parts. There is a play off between the level of protection / communication and the impact on the community. In brief, I understand that commercial companies have a greater need to communicate the trademark (as it may need to be used pro-actively to defend brand / IP rights). We have the trademark for defensive purposes, i.e. to make sure nobody can tell us not to use the name/brand and force us to change what we are building...
[6/9/15, 8:00:32 AM] Sven Laux: With regards to impact on the community:
[6/9/15, 8:03:29 AM] Sven Laux: There is a train of thought that community members might be put off by visible legalities such as trademark signs etc. The balance to strike is therefore for us to be able to defend ourselves should anyone challenge the name / brand (which we are able to do simply by having the trademark) and letting users feel free / unencumbered and not having to worry about us being legally "too on the case"...
[6/9/15, 8:04:30 AM] Sven Laux: In summary therefore, we have decided not to add the symbols as the level of greater protection is not necessarily required (after all we want people to come and use our code)

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 usage continues to prefer the hyphen—even in Microsoft's Language Portal.
• pop-up: When identifying small windows that open on top of other windows, "pop-up" will be spelled using a hyphen.
• website: Spelled as a single word: no space, no hyphen.
• step locking: As a noun referring to the technique whereby sections of a course are hidden until the preceding section (step) is completed, it is spelled as two words. As an adjective, in usage similar to "step-locking behavior is configured in articles.json", the two words are hyphenated.
• names of core plug-ins: When referring to the core plug-ins, the following names with capitalisation will be use: Text, Hot Graphic, Graphic, Blank, Narrative, Accordion, Media, Matching, Multiple Choice Question, Graphical Multiple Choice Question, Text Input, Slider, Assessment, Assessment Results, Trickle, Tutor, Page Level Progress, Bookmarking, Spoor, Resources, Box Menu, Vanilla.