You must log in to edit PetroWiki. Help with editing

Content of PetroWiki is intended for personal use only and to supplement, not replace, engineering judgment. SPE disclaims any and all liability for your use of such content. More information


Help:Creating quality topic pages: Difference between revisions

PetroWiki
Jump to navigation Jump to search
Line 29: Line 29:
==Table of Contents==
==Table of Contents==
(Automatically generated)
(Automatically generated)
A table of contents (TOC) is automatically generated from the section and subsection headings when at least four headings are created.
A table of contents (TOC) is automatically generated from the section and subsection headings when at least four headings are created.


[http://en.wikipedia.org/wiki/Help:Section#Table_of_contents_.28TOC.29 Read more…]
[http://en.wikipedia.org/wiki/Help:Section#Table_of_contents_.28TOC.29 Read more about this in Wikipedia…]


==Headings and sections==
==Headings and sections==

Revision as of 15:16, 3 September 2014

Page Title

(Required) (Title may be revised slightly during the editing process)

Article titles are based on how most people refer to the article's subject. There is often more than one appropriate title for an article. A good PetroWiki article title has the five following characteristics:

  • Recognizable – The title is a name or description of the subject that someone familiar with, although not necessarily an expert in, the subject area will recognize.
  • Naturalness – The title is one that readers are likely to look or search for and that page authors or subsequent editors would naturally use to link to the article from other articles.
  • Precision – The title is sufficiently precise to unambiguously identify the article's subject and distinguish it from other subjects.
  • Conciseness – The title is no longer than necessary to identify the article's subject and distinguish it from other subjects.
  • Consistency – The title is consistent with the pattern of similar articles' titles.

These characteristics should be seen as goals not as rules. For most topics, there is a simple and obvious title that meets these goals satisfactorily. If so, use it as a straightforward choice. However, in some cases the choice is not as obvious. It may be necessary to favor one or more of these goals over the others. The choice of article titles should put the interests of readers before those of page authors and those of a general audience before those of specialists.

Read more about this in Wikipedia …


Lead Section

(Required)

The lead section (also known as the lead, introduction, or intro) of a PetroWiki article is the section before the table of contents and the first heading. The lead serves as an introduction to the article and a summary of its most important aspects. The lead should be able to stand alone as a concise overview. It should define the topic, establish context, explain why the topic is notable, and summarize the most important points. It is the first part of the article most people read, and many only read the lead. Consideration should be given to creating interest in reading more of the article, but the lead should not "tease" the reader by hinting at content that follows. Instead, the lead should be written in a clear, accessible style with a neutral point of view; it should ideally contain no more than four well-composed paragraphs and be carefully sourced as appropriate.

Read more about this in Wikipedia…

Table of Contents

(Automatically generated)

A table of contents (TOC) is automatically generated from the section and subsection headings when at least four headings are created.

Read more about this in Wikipedia…

Headings and sections

A page can and should be divided into sections. Sections and subsections are introduced by headings. These headings clarify articles by breaking up text, organizing content, and populating the table of contents. Very short or very long sections and subsections in an article look cluttered and inhibit the flow of the prose. Sections are created by creating headings. Headings are written in sentence case. Heading names of sections (including subsections) should be unique on a page, using the same heading more than once on a page causes problems when linking to heading and/or subheadings. There should be a single blank line between headings.

Possible Section Headings below are to be used as a guide. These headings are intended to suggest or aid in the development of headings to match specific content need. Development of other headings is encouraged while following the stated guidelines covering heading names.

Standard Section Headings listed are automatically generated on every PetroWiki page. It is recommended that these headings stay on every page as placeholders for anticipated contributed content even if the initial page author(s) do not add content to the headings listed. These headings should be listed after topic specific headings (Possible Section Headings) placing them near the bottom portion of the topic page.

Read more…


Possible Section Headings

(One or all of these may apply to your topic)

  • History – A historic account of the topic
  • Purpose or Objective – The reason for its existence, its intended or desired result, or what issue does it resolve.
  • Type, taxonomy, or classification – Is there a category or group for this topic?
  • Functions – Actions or position this topic occupies in a particular situation or activity.
  • Features – What sets this apart or makes this topic important?
  • Advantages – What are the positives to this topic?
  • Disadvantages – What are the negatives to this topic?
  • Other considerations – What other things should the reader think about?
  • Nomenclature – Is there a set or system of names or terms used for this topic?
  • Gallery – Are there any images that relate to the topic to help illustrate the idea?
  • Graphs – Are there any graphs that relate to the topic to help illustrate the idea?

Note: Heading 1 – This heading is a placeholder for the first section of the topic page. On all new pages created, this heading must be revised or deleted.


Standard Section Headings

(These headings are auto generated)

  • References – Use this section for citation of items referenced in the text to show your sources. [The sources should be available to the reader, i.e., not an internal company document.]
  • Noteworthy papers in OnePetro – Use this section to list papers in OnePetro that a reader who wants to learn more should definitely read.
  • Noteworthy books – Use this section to list books that a reader who wants to learn more should definitely read.
  • Other noteworthy papers – Use this section to list papers not in OnePetro that a reader who wants to learn more should definitely read.
  • Online multimedia – Use this section to list multimedia that a reader who wants to learn more should definitely view. [The sources should be available to the reader, i.e., not an internal company document.]
  • External links – Use this section to provide links to relevant material on websites other than PetroWiki and OnePetro
  • See also – Use this section for links to related pages within PetroWiki, including a link to the original PEH text where appropriate.

Read more…


Paragraphs

Sections usually consist of paragraphs of running prose. Between paragraphs—as between sections—there should be a single blank line and the first line of each paragraph is not indented. The number of single-sentence paragraphs should be minimized, since they can inhibit the flow of the text; by the same token, paragraphs that exceed a certain length become hard to read. Short paragraphs and single sentences generally do not warrant their own subheading; in such circumstances, it may be preferable to use bullet points.

Read more…

Bullet Points

Bullet points should be minimized in the body and lead of the article, if they are used at all; however, a bulleted list may be useful to break up what would otherwise be a large, grey mass of text, particularly if the topic requires significant effort on the part of readers. However, bulleted lists are typical in the reference and reading sections towards the end of the article. Bullet points are usually not separated by blank lines.

Read more…

Images and graphs

It is a good idea to try to maintain visual coherence by aligning the sizes of images and graphs on a given page. When placing images, be careful not to stack too many of them within the lead, or within a single section. Images should ideally be spread evenly within the article, and relevant to the sections they are located in. If an article has many images—so many, in fact, that they lengthen the page beyond the length of the text itself—you can use a gallery. All images should also have an explicative caption. An image that would otherwise overwhelm the available text space on a 800×600 window should be shrunk or formatted as a panorama. As a general rule, images should not be set to a larger fixed size than the 220px default. Avoid referring to images as being on the left or right. Image placement is different for viewers of the mobile version of PetroWiki, and is meaningless to people having pages read to them by assistive software. Instead, use captions to identify images.

Read more…

Links

A key part with all PetroWiki articles is the interlinking with other relevant articles. Normally, the first occurrence of a word is the one chosen for a link. Do not link to the same article more than once in a section. Avoid creating adjacent links to separate articles, because the reader cannot tell whether the link is to one or two articles without pointing to the link.

Read more…

References

Commonly used types of citation

  • A full citation fully identifies a reliable source and, where applicable, the place in that source (such as a page number) where the information in question can be found. This type of citation is usually under the Reference heading and is the most commonly used citation method in PetroWiki articles.
  • A short citation is an inline citation that identifies the place in a source where specific information can be found also known as the parenthetical reference, but without giving full details of the source. Example (Williams 45) – these will have been provided in a full bibliographic citation in the Reference heading.
  • In-text attribution involves adding the source of a statement to the article text, such as Williams states that X.[5] This is done whenever a writer or speaker should be credited, such as with quotations, close paraphrasing, or statements of opinion or uncertain fact. The in-text attribution does not give full details of the source – this is done in a reference heading in the normal way.

Read more…

When and why to cite sources

By citing sources for PetroWiki content, you enable users to verify that the information given is supported by reliable sources, thus improving the credibility of PetroWiki while showing that the content is not original research. You also help users find additional information on the subject; and you avoid plagiarizing the source of your words or ideas by giving attribution. Citations are often discouraged in the lead section of an article, insofar as it summarizes information for which sources are given later in the article, although such things as quotations and particularly controversial statements should be supported by citations even in the lead. For an image or other media file, details of its origin and copyright status should appear on its file page. Image captions should be referenced as appropriate just like any other part of the article. A citation is not needed for descriptions such as alt text that are verifiable directly from the image itself, or for text that merely identifies a source.

Read more…

Citation Style

SPE has a *style guide that covers preferred citation formats. See Help:Reference and paper link format for more information and useful examples from the style guide.

Where possible, using the following will guide the reader to the exact documentation. These identifiers were designed to provide a permanent link to the online source of the document or other resource. This ensures that the reader can still get to the document even though the original source has changed or moved from its original location.

  • DOI – electronic serial or monograph publication (Digital Object Identifier)
  • ISBN – print or electronic book (International Standard Book Number)
  • ISSN – periodical publication at a specific media type (International Standard Serial Number)
  • WorldCat – a union catalog that itemizes the collections of 72,000 libraries in 170 countries and territories (World Catalog)
*While it is great if references to items on a page or links to papers follow this format, we don't want style to get in the way of people adding valuable citations and links into wiki pages. If you don't have all of the information specified in SPE's reference style, just try to include enough information that someone else could find the document you are referencing.

Read more…

Copyright and Acknowledgements

The content of this wiki is copyrighted by the Society of Petroleum Engineers (SPE). Authors are asked to transfer copyright at the time they save changes to a page. See Acknowledgements. Materials from this wiki cannot be reused without permission except under certain conditions. See Permissions.

Read more…


"Wikipedia:Manual of Style." Wikipedia. Wikimedia Foundation. 2014. Web. http://en.wikipedia.org/wiki/Wikipedia%3AManual_of_Style