ChemPRIME:Manual of Style

From ChemPRIME

Jump to: navigation, search

back to Help

The Manual of Style explains how to write an exemplar or other content so it is consistent with the style encouraged by ChemPRIME.

Contents

Creating an Exemplar

A good approach to creating an exemplar or other content is to rely on other help pages, a template, or a CoreChem page to give you the basic code, and then try to adjust to the MoS. Here is a list of features that ChemPRIME expects will be consistent across its pages:

  • Introduction - Begin an exemplar with a description of an interesting, real-life example and perhaps pose a question that can be answered using the exemplar's conceptual content (for more about planning and designing exemplars, see the Exemplars section in Collaborating with ChemPRIME;
  • Examples - Include clearly labeled example questions that apply to the topic of an exemplar; provide an explanation of how to approach and answer the question;.
  • Links - Incorporate links to other Web pages that are relevant to the page you are creating;
  • Tables - Whenever possible use bolding and centering;
  • Equations and formulas - use subscripts and superscripts (templates are available); chemical formulas and simple equations can appear within text, but display more complicated equations on a separate line using LaTeX (many common equations are already coded); do not use graphics for equations unless absolutely necessary;
  • Images - If an image is not a simple molecular structure, use a thumbnail and caption to explain;
  • Nomenclature - There are often multiple names for a chemical compound, an old, legacy name, and the International Union of Pure and Applied Chemistry(IUPAC) systematic name, particularly for organic compounds. Where appropriate, give both names, the older name in parentheses. For instance, C2H4 would be introduced as ethene(ethylene);
  • Media - Provide a description in text of each video or other media item so that its content can be understood by a user who cannot see it--especially for videos, describe the action; include instructions describing how inserted Jmols are intended to be interacted with; images should be mentioned in the text, and if appropriate, captioned
  • Documentation - Cite primary sources, even if they are in the public domain. Common chemical knowledge need not be cited, but references for examples and concepts that you had to research should appear at the bottom of the page;
  • ToC Sidebar - This expandable list of chapter headings should be included in pages that list tracks, in CoreChem pages, and in exemplars;
  • Standard Data - Use data from tables provided in the Resources and Tables page in all examples, problems, and text so that the same values are consistently available throughout ChemPRIME.

A well-structured and formatted page is Weak acids in foods - pH and beyond.

Documentation

Secondary Source

ChemPRIME, like Wikipedia (see Help:Citing Sources or WP:CS), contains only verifiable information, that is, information that comes from a published primary source that is referenced in the article. ChemPRIME is not the place to report new discoveries or personally observed phenomena. ChemPRIME articles are therefore secondary sources, but they must not be plagiarized.

Plagiarism and Copyright

All contributors should understand how to report information from a primary source without plagiarizing it, and the proper way to cite the source. ChemPRIME follows the Wikipedia:Copyrights Policies. An excellent source of information on the topic is the Indiana University-Bloomington Tutorial on How to Recognize Plagiarism, which includes a test that might be giving to potential student contributors.

Articles may be referenced by surrounding them with the <ref> and </ref> tags, like this

<ref>https://www.indiana.edu/~istd/plagiarism_test.html test</ref>

Then insert a section at the end of the article where the citations will be automatically numbered and collected, as follows:


==References==
<references/> 

This article has a section to illustrate how the reference tag above will appear when inserted at the end of this sentence, if the References section is added at the end of the article[1]. In Wikipedia, search for the page Help:Footnotes.

Public Domain Resources

There are lots of resources in the public domain, and many are described in the Wikipedia page WP:PDR. The Wikipedia page WP:PD describes policies regarding Public Domain documents.

Links to Sources

Alternatively, any text can be made into a hot link to a reference, as we've done above. For the Plagiarism Test Site, the code looks like this:

[https://www.indiana.edu/~istd/plagiarism_test.html test]

So that the word "test", inserted after the URL, is the highlighted hotlink in the article (as above). If the word "test" is omitted, the URL appears as the highlighted hotlink. If the source is in a ChemPRIME article, double brackets are used, the name of the article is entered, and a "pipe" (vertical bar above the backslash on most keyboards) is used for the highlighted text:

The ChemPRIME stragegy is described on[[What Is ChemPRIME? |this page.]]

Gives

The ChemPRIME stragegy is described on this page.

ToC SideBar and Navigation

The ToC SideBar must be placed at the beginning of:

  • Base pages that list tracks
  • CoreChem pages with textbook information
  • Exemplars written by ChemPRIME users

This covers almost every page a ChemPRIME user will write, so when in doubt, start a page with the ToC Sidebar.

The SideBar defines which "chapter" of chemistry the page is included in. The code {{ToC SideBar|chX}} should be placed at the beginning of each page. "X" refers to the chapter number as ordered in the ToC, beginning with Chapter 1 (Introduction: The Ambit of Chemistry) and ending with Chapter 22 (Metals). By adding the sidebar, readers will be able to quickly navigate to other topics in the chapter, and be able to navigate to other chapters as well.

Any section within a chapter should be labeled with the respective chapter number. For example, Aromatic Hydrocarbons is a section within Chapter 8 (Properties of Organic Compounds and Other Covalent Substances), so the ToC code at the top reads {{ToC SideBar|ch8}}.

In addition to using the ToC SideBar, add a link back to the tracks page under which your article is included. For instance, Optimizing Gunpowder Composition, an exemplar in Equations and Mass Relationships in Forensics, provides a link at the top of the page back to Equations and Mass Relationships.

We've used a link at the top of this page (and below) to navigate back to the main Help page with the wiki code:

Wiki Code How Link Appears
<font size="2">''back to'' [[Help:Contents |Help]]</font>
back to Help

Images

Images are crucial for depicting molecular structure and physical properties of chemical equations. It is encouraged the chemical equations be typed out using code rather than an image of a chemical equation be uploaded.

The basic code for displaying an image is:

[[Image:name|format|alignment|size|caption]]

The meaning of each field and how to select options are explained in Help: Images.

There are two preferred formats for images on ChemPRIME:

  1. Most images, including all images with a non-transparent background, should be enclosed with a thumbnail, kept under 500px in width, and given a caption with a Figure number in bold.
  2. Small images without captions, which are usually simple 2D representations of molecules such as Lewis diagrams. The page CoreChem:Exceptions to the Octet Rule provides examples of a number of images using this format. Adding captions to these images would make the page more difficult to read and clutter the page.

Examples of the standard format for each type are shown:

Format and Use Wiki Code Image
Caption, on CoreChem:Indicators [[Image:Phenolphtalein.jpg|thumb|none|300px|'''Fig. 2 Phenolphtalein at different pH levels. Notice the distinctive color at pH 8-12''']]
Fig. 2 Phenolphtalein at different pH levels. Notice the distinctive color at pH 8-12
No caption, on CoreChem:Ethers [[File:1- and 2-propanol.jpg]] Image:1- and 2-propanol.jpg

Use these codes for standard formatting. The Help: Images page provides in depth descriptions more advanced image formatting.

back to Help

Tables

Tables offer a concise method for displaying data and conveying chemical ideas. Using the same formatting for all tables on ChemPRIME improves the overall presentation of ChemPRIME. It is highly encouraged to create tables in wiki-code instead of uploading an image. Wiki-code tables offer the advantage that text can be searched and can be read by screen readers.

In addition, we have selected a common format for our wiki-tables. Tables are formatted with a 500 px width with border of 1 px, no cell spacing, and variable cell padding. The first row (column headings) has gray background and the column labels are written with bold font with variable alignment. Note that the width of the table has been set as 500 px, this is the maximum value for the table to be displayed properly in ChemPaths. As an example:

{| cellspacing="0" cellpadding="15" border="1" style="width: 500px;"
|-
| bgcolor="#cccccc" align="center" | '''Header 1''' 
| bgcolor="#cccccc" align="center" | '''Header 2''' 
| bgcolor="#cccccc" align="center" | '''Header 3'''
|-

| row 1, cell 1
| row 1, cell 2
| row 1, cell 3
|-
| row 2, cell 1 || row 2, cell 2 || row 2, cell 3
|}

Creates the table:

Header 1 Header 2 Header 3
row 1, cell 1 row 1, cell 2 row 1, cell 3
row 2, cell 1 row 2, cell 2 row 2, cell 3

The first six lines of this code (to the second |- mark) are necessary to set the table in this preferred format. If you are making a table with more or less than three columns, this will vary, as lines 3-5 define column headings. To change column headings, just copy and paste one of these three lines, and replace the text that corresponds to the column heading at the end of each line with the title of the column you want. Deleting or adding lines in at this point in the code will change the number of columns in the table.

For general formatting, note that columns can be created with a | at the beginning of a line, or a double pipe within the line. Either code works. Also, the |- symbol starts a new row, the {| symbol starts a table, and the |} symbol ends the table.

Another format used on ChemPRIME is the Embedded Table, which offers a way of putting tables side-by-side, or presenting images in a table.

{| cellspacing="0" cellpadding="15" border="1" style="width: 500px;"
|
{| cellspacing="0" cellpadding="15" border="1" style="width: 200px;"
|+ '''Title 1'''
| bgcolor="#cccccc" align="center" |'''head 1'''
| bgcolor="#cccccc" align="center" |'''head 2'''
| bgcolor="#cccccc" align="center" |'''head 3'''
|-
| A1 || A2 || A3
|-
| B1 || B2 || B3
|-
|}
|
{| cellspacing="0" cellpadding="15" border="1" style="width: 200px;"
|+ '''Title 2'''
| bgcolor="#cccccc" align="center" |'''head 1'''
| bgcolor="#cccccc" align="center" |'''head 2'''
| bgcolor="#cccccc" align="center" |'''head 3'''
|-
| C1 || C2  || C3
|-
| D1 || D2  || D3
|-
|}
|}
Title 1
head 1 head 2 head 3
A1 A2 A3
B1 B2 B3
Title 2
head 1 head 2 head 3
C1 C2 C3
D1 D2 D3

The help page on Tables gives a more in depth explanation of how to format tables.

Media

In addition to image forms of media frequently used in ChemPRIME are Jmols and Videos. When adding Jmols or videos to a page, it is important to describe them in the text, both to explain how they related to topic of the page, and also to describe the video or Jmol, in case the user is unable to view the media.

Videos

Videos can either be taken from the Chemical Education Digital Library (ChemEdDL), which includes the JCE Chemistry Comes Alive! collection along with other videos, or videos can be externally linked to on Youtube.

In the case of ChemEdDL videos, the <chemeddl-video></chemeddl-video> video tags can be used to embed these videos onto the page. Make sure the videos are properly explained in the article text. CoreChem:The Rate of Reaction provides an example of how this may be done.

Youtube videos currently cannot be embedded on a page. Instead, it is possible to provide an external link to Youtube videos helpful in demonstrating a concept. See Links to External Pages for the proper syntax. In this case, the video content can be explained in the text containing the link. The beginning of CoreChem:Titrations provides an example of how this may be done.

The videos help page provides more in depth explanation of the actual syntax needed to add videos.


Jmols

Jmols allow viewers to manipulate 3-D models of molecules, an invaluable teaching tool in chemistry. Using the Jmol tag associated with the Molecules 360 Database many different 3D molecules can be embedded in a page. Depending on the concept to be shown, different formatting guidelines apply:

  1. Just displaying a 3D model: Sometimes, it is important to add a 3D model simply to show what another molecular representation, such a molecular formula, lewis structure or stick diagram is representing three dimensionally. In this case all the extra features of Jmol applet are unnecessary, and a simpler, twirlymol representation should be used. These models can be treated similarly to un-captioned images, or they may be displayed in a gallery or table if they are being compared to other molecules, or other representations of the same molecule.
  2. Displaying Molecular Properties: Jmol can be used to show more in depth molecular features, ranging from bond distances and bond angles, to elctrostatic potential maps, to molecular orbital calculations. In order to take advantage of these features instructions need to be specifically given in the article on how view the correct molecular property. Often, it is best to turn these into examples in the text.
  3. Showing Lewis Structures: Jmol can also be used to show Lewis structures of molecules in the database. CoreChem:Examples of Lewis Structures show an example of both lewis structures and the twirlymol application as well.

The Jmols help page provides more information on the syntax used to display Jmols.


Examples

Examples are "problem set" type questions which allow students and users to test whether they are understanding the content of an article, and also give students a sense of the types of questions they might see if tested or quizzed on a subject. In addition, examples help to ensure that an exemplar is covering the same concepts seen in other tracks, so that regardless of whether a student reads the CoreChem:Density page, or an exemplar on Density in Geology, Density with Cultural Connections, or any of the Density tracks, they will still be able to answer similar questions about density.

The general formatting conventions for an example are:

  • Each example is numbered according to its position on the page and bold.
  • The example is separated from the rest of the text using a horizontal bar. The questions and solution portion of an example are separated by a horizontal bar as well.
  • Equations are displayed as text or LaTeX code on a separate line. Uploaded images of equations are discouraged. Look at Help:Equations Tips and Tricks for tips on how to write equations on ChemPRIME, especially equations commonly seen in chemistry.

The following is an example of how this sort of formatting works:

Wiki Code How the Example Appears
---- '''EXAMPLE 1''' This is where the question or set of questions would be asked. As the first example on the page, this is titled with a bold "Example 1". Horizontal bars separate this from the text above and solution below. ---- '''Solution''' The method for solving the question asked above is displayed here. This likely includes showing the necessary equations, and the plugging in values for the question. Horizontal bars separate this from the question above and the continuing text below. ----

EXAMPLE 1 This is where the question or set of questions would be asked. As the first example on the page, this is titled with a bold "Example 1". Horizontal bars separate this from the text above and solution below.


Solution

The method for solving the question asked above is displayed here. This likely includes showing the necessary equations, and the plugging in values for the question. Horizontal bars separate this from the question above and the continuing text below.


back to Help

References

  1. https://www.indiana.edu/~istd/plagiarism_test.html
Personal tools