CZ:Article mechanics: Difference between revisions

From Citizendium
Jump to navigation Jump to search
imported>Larry Sanger
m (Text replacement - "CZ:Article Mechanics" to "CZ:Article mechanics")
 
(107 intermediate revisions by 34 users not shown)
Line 1: Line 1:
== The nature or purpose of an encyclopedia article ==
<center><div class="usermessage plainlinks">'''This is a summary of  [[CZ:Article mechanics Complete|The complete document here]].'''</div></center>
{{TOC|right}}


While the ''Citizendium'' may not (yet) call itself an encyclopedia, its aim is to build up a body of articles that serve as encyclopedia articles.  These articles cover, at a very general level, every aspect of their topics. Their broad scope is perhaps what most clearly distinguishes encyclopedia articles from ordinary expository essays.  Therefore, the purpose of every article (as distinguished from lists and other supplementary material) in the ''Citizendium'' is to introduce every aspect (or many aspects) of the topic named in its title, but at a very general level.
''See also [[CZ:Content_Policy|content policy]].''


Introductions differ from mere summaries or lists of information.  An introduction is an extended, connected piece of prose, meant to be read all the way through. It is not merely a list of facts.  It places what facts it presents into a context that makes them meaningful to someone who presumably ''needs'' an introduction.  Indeed, the very notion of an introduction carries in it the idea that the topic introduced is new to its ideal reader.
[[Citizendium]] aims to build a body of [[CZ:Articles|articles]] that ''introduce'' their topics in an accessible, yet authoritative, way. An article is not a mere summary or list of information, but a connected piece of prose, meant to be read all the way through. Articles must be selective in what they present, but need not be ''brief''; they should say what they need to as clearly as possible, in a concise and interesting way.


Introductory articles, to be read and used by their intended audience, must be somewhat selective and simplified in the information they present. If an article contains information presented too densely, or in too abstract a way, it becomes merely a catalog or record of what experts know--of some interest to experts, perhaps, but not to people who actually need an introduction. This does not mean that an introduction must be ''brief,'' but that it spend the space needed to make whatever it does say clear to a university-level audience that is prepared to receive an entree to the topic.  In other words, a ''Citizendium'' article is an opportunity to show off not your erudition but your ability to make the difficult seem easy.
==Opening section==
The opening section should ''always'' be introductory, so the heading "Introduction" is unnecessary. The first paragraph usually begins with a definition, and we '''bold''' the title of the article in the first sentence, e.g.: "'''Philosophy''' is an abstract, intellectual discourse..." The first paragraph should contain a concise and neutral answer to "Why is this topic important (or interesting)?" If the topic is a person, say what the person is best known for; if an event, summarize its impact; if a place, describe what makes it notable. The rest of the opening section should give the background needed for understanding the rest of the article. The opening section can be a ‘’summary’’ of the article, but a brief outline of the article structure may be better if the article is very long.


== Introductory material ==
== The article body ==
 
Generally, articles need a plan that lends coherence and flow and invites readers to keep reading. A task of editors is to help plan articles, and this may be discussed on the Talk page. Generally, major achievements of individuals should be presented before minor ones; the basic tenets of a theory before derivative ones; and earlier events before later ones.
=== Matter placed between the title and the first sentence ===
 
Do not place a heading, such as "Introduction" or "Preface" or "Definition," between the article title and the first sentence.  The first heading belongs ''after'' the first section, which should ''always'' be introductory.
 
There must be an excellent reason to place ''anything'' between the title and first sentence of an article.  Exceptions are few and enumerable.
 
Approval notices are always appropriate, as are links back to the article page from a draft page.  (See [[CZ:Approval Process|Approval Process]].)
 
Links to [[CZ:Disambiguation Pages|disambiguation pages]] (pages that point to several different articles that have the same title; think "Paris" or "Mars") should be placed ''only when there really is a need for such a link.''  Thus, for example, if we decide to use the page titled [[Paris]] for the French city, then considering that ''some'' people will go to that page looking for an article about the Greek hero under that title, we should probably have a disambiguation notice atop that page.  On the page titled [[Paris (Greek hero)]], however, there is no need for such a disambiguation notice at the top of the page, because it is highly unlikely that anyone will arrive at [[Paris (Greek hero)]] looking for an article about any other sort of Paris.
 
Links to [[CZ:Confusable Pages|confusable pages]] (other pages with topics, but not necessarily names, that are easily confusable with the present page's topic; think ethics vs. morality, or fiddle vs. violin) are acceptable ''only if there really is a need for them.''  The rule we may use to make the decision whether to have a notice about a confusable page is: two pages, A and B, should interlink with "confusable page" notices ''only if'' the topics are commonly confused ''and'' readers can be expected to read A believing that they have found all the information the ''Citizendium'' has about B.  For example, we might well have separate articles about [[ethics]] and [[morality]].  But these concepts are often not distinguished, and few people can say with any clarity what the difference is between them; moreover, it's entirely possible that someone might read our [[ethics]] article expecting to find all the information we have about morality, as well.  In such a case, we should place a notice atop [[ethics]] saying, for example, "''For the history of differences between actual moral practices, see [[morality]].  This article concerns the philosophical discipline.''"  We would then place a similar notice atop [[morality]].
 
=== Bold titles ===
 
In most articles, we should '''bold''' the title of the article.  For example:
 
:'''Philosophy,''' both the field and the concept, is notoriously hard to define. The question "What is philosophy?" is itself, famously, a vexing philosophical question. It is often observed that philosophers are unique in the extent to which they disagree about what their field even is.
 
But on some pages this is unnecessary, particularly where it would produce strange or nonsensical results.  Such pages include lists, as in [[list of snake scales]], or where the title of the article is an idiosyncratic phrase that does not name a single, particular item to be defined or briefly described, such as [[potassium in nutrition and human health]].
 
=== The first sentence ===
 
What the first sentence of the article should look like depends on whether the article concerns a concept or, instead, a particular thing.
 
Generally, in articles about concepts, or where the word in the title has a definition, the first sentence in the article is a definition.  For example:
 
:'''Dermatology''' is the specialty of medicine concerned with the [[skin]] and with the skin appendages ([[hair]], [[nail|nails]], [[sweat gland|sweat glands]], etc.).
 
If, however, there is no agreed-upon definition, and particularly where the disagreement about the definition is an important aspect of the topic--one thinks of [[freedom]] or [[racism]]--it is preferable ''not'' to begin with a single (and controversial) definition.  In such cases, it is actually preferable to begin in some other way, even by describing the difficulty of or the controversy over the concept.  (See the "Philosophy" example above.)
 
In articles about particular things, such as persons, historical events, or publications, it is usually preferable to begin the article with a description of what the item in question is most notable for:
 
:'''Princeton, New Jersey''' is located in Mercer County, New Jersey, United States, and is best known as the home, since 1756, of Princeton University.
 
:'''William Shakespeare''' (baptised April 26, 1564 – died April 23, 1616) was an English poet and playwright widely regarded as the greatest writer of the English language, as well as one of the greatest in Western literature, and the world's preeminent dramatist.
 
=== Etymologies ===
 
Most etymologies of terms are not so interesting or important that they deserve more than cursory treatment.  So, usually they should be placed in parenthetical clarifications
 
:'''Physics''' (from the Greek ''physikos,'' nature) is the science of nature at its most fundamental form...
 
or [http://pilot.citizendium.org/wiki?title=Biology&oldid=100047130#_note-0 even in footnotes,] where the etymology is of interest, but ought not to interrupt the flow of the article.
 
But occasionally the etymology of a term is itself of such interest that it can be made a subject of its own sentence, paragraph, or even section:
 
:The word [[morphology]] came into English in the mid 19th century from Greek words ''μορφή (morphi)'' meaning "shape or form" and ''λόγος (logos)'' meaning "speak". In English the suffix "-(o)logy" means "the study of". For ancient Greeks, study often involved a great deal of debate; and this is still true for scientists today.
 
A lengthy etymology is called for particularly when discussion sheds some special light on other than merely linguistic facts.  A classic example can be found, again, in [[philosophy]].
 
Authors are encouraged to follow one of the above conventions for reporting etymologies.
 
=== Definitions ===
 
To learn how to write a good definition, you might consult the many good explanations found in introductory logic and critical thinking textbooks.  The requirements we have will be approximately the same that you will find there; see [[CZ:Definitions#Standards_for_good_definitions|this discussion]] for some helpful hints.
 
Perhaps most general terms in the ''Citizendium'' have more or less agreed-upon definitions.  But there are many terms of which there is no agreed definition, and where the definition is in fact a central matter of dispute.  This is true of many abstract concepts in the humanities and social sciences, and sometimes in the hard sciences.  We must weigh two concerns: on the one hand, the desire of the user for a straightforward account of the topic; on the other hand, an unbiased article, i.e., one that does not violate our [[CZ:Neutrality Policy|Neutrality Policy]].
 
There are several acceptable ways to solve this problem:
* Provide a single vague definition, in plain terms, which does not engage the main topics of dispute.
* Provide a quick run-down of several main definitions.
* Explicitly discuss the difficulty of defining the term; provide examples.
 
It is rarely if ever acceptable, however, to begin an article with just one idiosyncratic definition when there are many importantly different definitions--particularly when our opening with that definition would imply an endorsement by the ''Citizendium'' of a particular controversial view.  If for whatever reason this were to be the only reasonable way to begin an article, one would have to qualify the definition.  One might say that it is so-and-so's definition, that we (the ''Citizendium'') are using the definition in order to give the reader a rough idea of the concept, but that there are many other ways of understanding the concept, and that we do not particularly favor this one.
 
=== The first paragraph ===
 
The first paragraph of articles should typically (not always: see above) begin with either a definition or a description of that for which a particular thing is best known.  As to rest of that opening paragraph, typically, it should begin a narrative, and be written in an interesting and informative style.  It should not simply be a summary of facts stated within the main body of the article.  It should attempt to describe a concept that ties together the entire article into a cohesive whole.
 
It should also encourage reader interest.
 
=== The introductory section ===
 
Articles begin with an introduction.  The introductory section of an article (or, what comes before the first section marker) should ''at least'' give background necessary for purposes of understanding the rest of the article.  What else an introduction might accomplish depends on the article.  Generally, what ''sort'' of introduction is needed depends entirely on the subject matter and the approach that the article takes.  For example, if the article concerns some abstruse concept, the entire introductory section might be devoted to clarifying the concept.  If the article itself is primarily a narrative, the introduction would do "stage setting" for the narrative, such as introducing characters and preparing readers for key events.  If the article concerns a controversy, then the introduction might characterize the controversy in a general way, introduce key players, define positions, or do other such stage-setting.
 
It is acceptable for the introduction to be a summary of the topic itself, that is, to sum up the information found in the article.  This is not necessarily the best use of the space, however.  Authors are asked to consider whether a summary of the information found in the article clarifies matters for the user particularly; often, the answer will be "no."
 
In fact, however, a brief outline of the article structure--as distinguished from a summary of the information contained in the article--is ''preferable'' when the article is particularly long.  If the introduction ''contains'' such an outline, the summary should come at the end of the introduction.
 
== The structure of the article body ==
 
=== Narrative coherence and flow ===
 
Articles should be written to be read all the way through. To be most attractive to readers, they need a unifying plan, or a narrative, which lends coherence and flow and invites readers to keep reading. This means that articles should not be modular or mere collections of facts that can easily be reshuffled.
 
But this is not an absolute rule that must be followed at all costs.  Certain parts of articles may stand-alone, such as tables of supporting reference material or useful lists. Contributors should bear in mind, however, that such material should not "speak for itself."  For example, an article might include a timeline, a list of subdisciplines, or a list of leading examples. If material is important enough to include in the article, then some of it should be important enough to be at least summarized in the narrative itself.
 
Moreover, sometimes a topic involves two or more different kinds of information with no plausible way to string them together into a single narrative. In that case, it is all right to have a break in the article between the separate narratives.
 
Some articles in Wikipedia, particularly about disciplines and other broad topics, are in the form of a list of summaries of subtopics. For example, an introduction to physics might consist of a series of sections listing the subject's different branches, each with its own introduction.  This is to be avoided: a mere list of subtopics with introductions will rarely if ever succeed in ''effectively'' introducing the topic itself.  It is preferable to choose an approach that will encompass the diverse subtopics--although doing so may require considerable creativity.
 
An imperfect indicator that the article has little narrative coherence is that it has a long series of short sections, as does [http://en.wikipedia.org/w/index.php?title=Ethics&oldid=116467902 this Wikipedia article.]  Generally, it is important to avoid overusing section titles (see below).
 
A central task of Citizendium editors is to provide leadership in deciding a unifying plan for articles on topics of their expertise. The plan can be discussed on the article's talk page, if it is not obvious from reading the article itself. Indeed, particularly for longer articles, it may help to conclude the introductory section with a summary that makes the article's plan clear.
 
=== Prioritization of article sections ===
 
As a general rule, to which there are many possible exceptions, information that is most important, fundamental, or earliest should be presented first.  Major achievements of individuals should be presented before minor ones; the basic tenets of a theory or system of thought should be presented before derivative ones; earlier events should be recounted before later ones.  Where there is disagreement as to what is most important, the order can be determined by reference to the views of those concerned, or the "constituency" of the article, and with special but not exclusive weight being given to expert opinion.
 
The main category of exception will probably be due to the order in which sections should appear as determined by the article plan, or by a [[#Standardized information|standard order]] for the kind of article that it is.  For example, an article that recounts the achievements of [[Abraham Lincoln]] in historical order would put the [[Emancipation Proclamation]] near the end of the article.  But the Emancipation Proclamation is one of Lincoln's most important achievements, and so we would seem to want to place this first.  A suitable compromise would be to have a paragraph about the Emancipation Proclamation in the introductory section of the article, or in a "Major Achievements" section that would come immediately after the introductory section.


=== Section titles ===
=== Section titles ===
 
Section headings help both readers and authors, but too many can be ugly and distracting. A well-organized narrative is [http://pilot.citizendium.org/wiki?title=Biology&oldid=100047130 this "Biology" article].
Section titles should be descriptive, lowercase, and necessary.  A new section is rarely needed for fewer than three paragraphs; but a single section could be suitable for considerably more than that.
 
Many and frequent section headings are sometimes used to structure an otherwise disconnected collection of data. A plethora of headings are really not necessary in a well-organized narrative, as [http://pilot.citizendium.org/wiki?title=Biology&oldid=100047130 this "Biology" article] demonstrates.
 
Top-level headings are created with ''two'' equals signs, like this (but flush left):
 
:<code><nowiki>== World War II ==</nowiki></code>
 
Subsection headings (necessary only for very long sections) are created using ''three'' equals signs.  We avoid headings surrounded on both sides by just ''one'' equals sign, because that will produce the same font size as the article title.  It is not necessary to bold section titles.


=== Standardized information ===
=== Standardized information ===
 
If there is to be an article about every species of snake, it is convenient to have a standard structure. When beginning an article, authors should check articles on closely related themes to see if a standard structure has already been established by others. ''Citizendium'' [[CZ:Workgroups|workgroups]] will ultimately settle on any such standard practices.
We might say that there are some articles that have a standardized structure.  If there is to be an article about every species on Earth, that is over one million articles, it is probably most convenient for the user to have a standard order in which facts are presented. Other kinds of articles that might benefit from some standardization would be biographies and articles about countries, cities, and other geopolitical areas.
 
''Citizendium'' [[CZ:Workgroups|workgroups]] will settle ultimately on any such standard practices.  Individual contributors may make proposals, but only workgroups, working according to a procedure yet to be decided, may actually settle upon proposals.
 
It will be important not to impose ''too'' much standardization, for the simple reason that standardization tends to work against readability and narrative flow.  Moreover, within any given category, there are bound to be many exceptions and much variation.  Any proposals for standardization should bear this in mind.
 
== End matter ==
 
There are several standard kinds of end matter that are appropriate or even, in some cases, strongly recommended.
 
There is a proposal under consideration that will amend this section greatly.  See [[CZ:Subpage Pilot]].
 
=== External links ===
 
External links are preferably bulleted and neutrally annotated.  "Deep links" to the page or section of a website most relevant to a given topic are preferable to links to entry pages that are several mouseclicks away from the most relevant content.
 
Links to external websites are not to be placed within articles themselves.  The main reason for this rule is simply that it is poor style: external links belong in footnotes.  Moreover, always link words and phrases to ''Citizendium'' articles rather than external sources of information about the word or phrase--even if we still lack an article on the subject.
 
We have rules against self-promotion in our [[CZ:Policy on Topic Informants|policy on topic informants]], and similarly, contributors are not to add links to websites that they manage, unless it is evident from a Google search (or other adequate proof) that the website is in fact a leading ''and reliable'' source of information on a topic.


=== Citations ===
=== Citations ===
 
See [[Help:Citation style]]. We expect citations in about the same quantity as in academic encyclopedias. '''Citations are not usually needed for information that is common knowledge among experts.''' But the following categories of claims generally do need citation:
The ''Citizendium'' requires citations in about the same quantity, for about the same reasons, that citations are used in specialized academic encyclopedias. Generally, the following are categories of claims that either require, or might at least benefit from, support by a citation:
* direct quotations
* direct quotations
* claims with unique sources (such as survey results, or the finding of a particular paper)
* claims with unique sources (such as survey results, or the finding of a particular paper)
Line 152: Line 25:
* claims central to the article
* claims central to the article


Note that citations are not needed for information that is common knowledge among experts.
Wherever possible, give an online link for any reference, at least to the abstract (via, for example, a PubMed reference.)


Please only very sparingly use multiple citations for a single sentence, one per source; it is preferable, as in ordinary academic writing, to include several sources in one citation.
Rather than use several references in one sentence, it may be better to include several sources in one citation.


An informational endnote, without a citation, may be used to make important elaborations or clarifications of the text, when including the elaboration in the text itself would break the flow of the discussion.  Such endnotes are to be used only sparingly--not more than a few in any given article.  They should not be used to state opinions, as they often are in scholarly work.
'''It is important to give full citation credit to imported illustrations, where for example these are imported from open-access journals.'''


See [[Help:Citation style]] for details.  We have not yet settled upon a single citation style.  Our apologies for the confusion, but we are still negotiating.
== Definition ==
See [[CZ:Definitions]]. Every page should have a subpage/Definition that only contains a short sentence explaining the topic of the page:
* Maximum one sentence (no more than 30 words/150 characters, ignoring formatting characters).
* Don't include the term defined in the definition itself.
* Start the text with a capital letter and end with a period. (Use a semicolon, if necessary, in between, but no period.)
This definition is mainly used on the /Related Pages subpage where
: <nowiki>  {{r|number}} </nowiki> and <nowiki> {{r|no number}} </nowiki>
produce
: {{r|number}} and {{r|no number}}
If there is a main page, but no /Metadata page (e.g., if the page is a redirect),
the template shows the link in boldface.
A special case of this is a ''[[CZ:Lemma article|lemma article]]'', which is an article
that has a main page containing only the <nowiki>{{subpages}}</nowiki> template. In this case,
the /Definition is transcluded to the page:
: {{r|foo lemma}}
A definition intended for a lemma article may be longer than a "normal" definition. Lemma articles may have Related Articles, Bibliography and External Links subpages, which must not have the <nowiki>{{subpages}}</nowiki> template.  At any time, a lemma article may be converted to a regular article; at that point, part of a long definition usually will move to the main page.


=== Further reading ===
== Metadata ==
See [[CZ:Article structure#Metadata]]


The "Further reading" section best takes the form of an annotated bibliography.  Note, however, that books consulted during writing ''need not'' and ''should not'' be listed here unless they meet the other criteria for listing.
Organizational and technical information related to a page is stored on a special template page Template:''ArticleName''/Metadata:
Title, title for alphabetization, workgroups, status, approval data, etc.
It also contains the workgroup categories.
(Please note that [[CZ:Categories|categories]] are only used for administrative purposes.)


Generally, these should be books and other written material that, in the opinion of ''Citizendium'' contributors--and ultimately editors who are specialists in the topic of the article--represent the most important, seminal, and useful texts specifically about the topic of the article.
== Subpages ==
Factual material, where there is no real narrative flow, may be best presented in [[CZ:Subpages|subpages]]. The standard subpages will always include:


Annotations, clarifying why an item is listed ("one of the most commonly used texts in this field"; "the paper which originally defined the concept"), are strongly preferred.
===Related articles subpage===
This connects each article with related articles and offers greater insight into the underlying conceptual structure of the encyclopedia. Related Articles subpages generally are organized into a few Parent Topics, which are more general topics within which the current article is located; Subtopics, which are aspects of the main topic worth separate discussion; and Related Topics are "close tangents" which take the discussion off in new directions. The article on [[World War I]] includes Parent Topics on War and [[Nationalism]], Subtopics include famous battles such as [[Gallipoli]] and the [[Somme]], and Related Articles include [[Trench warfare]] and [[Mustard gas]].


=== Source texts ''or'' Works ===
=== Bibliography subpage===
This is an annotated [[CZ:Bibliography|bibliography]]: books, articles and other material that are important and useful, clarifying why an item is listed ("one of the most commonly used texts in this field"; "the paper which originally defined the concept"). For example, historical topics may list and annotate the leading sources for information on a topic, and articles about authors may list their major works. If an item is available online, the annotation should provide the link. (Here are the [[CZ:Citation templates|citation templates]].) How to write annotations is discussed by the [http://www.loc.gov/nls/other/annotation/revised/creating%20an%20annotation%20(without%20title%20page).pdf Library of Congress publication ''Creating an Annotation''.]


Historical topics should list and annotate the leading published, written sources for information on a topic.  Similarly, articles about authors should have a list of works.
Articles may also have a "Suggested reading" section at the end of the main article that presents 5-10 publications suitable for beginners, especially if they are on the web.


=== Subtopics ''and'' Related topics ===
=== External links subpage===


Rather than use categories, as Wikipedia does, contributors can compile lists of "Subtopics" and of "Related topics".  Right now, many articles have "See also" sections.
''See [[CZ:External Links]]''


''To elaborate.''
External links should be neutrally annotated.  Links to external websites should not be placed within articles but in footnotes.  Link words and phrases to ''Citizendium'' articles rather than external sources of information --even if we still lack an article on the subject. We have rules against self-promotion ([[CZ:Policy on Topic Informants|policy on topic informants]]), and contributors should not link to websites that they manage, unless it is very evident that the website is a leading ''and reliable'' source of information.


=== Categories ===
=== Optional subpages ===
''See [[CZ:Subpages#Optional subpages|list of optional subpages]]


For ease of editing by other contributors, categories should be placed at the ''bottom'' of the page.
Many other subpages may be included; the current list of subpages includes Works, Discography, Filmography, Catalogs, Timelines, Gallery (Images), Audio and Video pages, Computer Code, Tutorials, Student-level discussions, Signed Article, Function, Addendum, Debate Guide, Advanced and Recipes.
<br>There are also some ''[[CZ:Article-specific subpages|article-specific]]'' subpages (for certain topics) which are not yet fully acknowledged.
<br>Please note [[CZ:Categories|Categories]] are used for administrative purposes (workgroups, etc.) only.
Lists of topics are compiled on appropriate /Catalogs subpages.


Currently, there are only a very small number of categories that are widely used on article pages.  These include [[:Category:CZ Live]], the various [[CZ:Workgroups|workgroup]] categories, and [[:Category:Needs Workgroup]].
== Miscellaneous style guidelines ==
 
''See also [[CZ:Sage_advice_on_writing_CZ_articles|Sage advice on writing CZ articles]].
Please do not create new Wikipedia-style subject categories.  If a category has already been created, we will not delete it in the interests of preserving information, but we may at some future date start an initiative to add "Subtopics" and "Related topics" and "List of"-type pages so as to perform a similar function to category lists.
 
== Grammar, spelling, punctuation, and usage ==
 
''To draft.''


Please refer to Strunk and White's ''Elements of Style'' for basic points--if, for example, you are a high school or college student and have never read it, or if you are not a particularly experienced writer, you really ''must'' do so.  (All right, not really, but it's a great idea.  The first edition, which is still quite useful, is available [http://www.bartleby.com/141/ here.])
Craft articles for maximum readability. Many topics may be impossible for a non-specialist fully to understand, but if an advanced piece of text ''can'' be written to make it more accessible to nonspecialists, then it ''should'' be. Professionals are often accused of writing jargon that is decipherable only by people in their fields; our task is to "translate" the jargon into elegant prose.  
 
For American English articles, please consult ''The Chicago Manual of Style'' for matters of formatting, punctuation, and the like.  Consult Garner's ''Dictionary of American English Usage'' for issues of usage.
 
For British English articles, consult Fowler's ''Modern English Usage'' for issues of usage.  Americans will also find this very useful.  (We haven't settled upon a manual for formatting, punctuation, etc., of British English.)
 
== Miscellaneous style guidelines ==


=== Craft articles for maximum readability ===
=== Grammar, spelling, punctuation, and usage===
Strunk and White's ''Elements of Style'' is useful; the first edition is available [http://www.bartleby.com/141/ here.] For American English, please consult ''The Chicago Manual of Style'' for matters of formatting, punctuation, etc. and Garner's ''Dictionary of American English Usage'' for issues of usage. For British English, consult Fowler's ''Modern English Usage''.


Craft articles for maximum readability. Many topics are inherently complex and impossible for a nonspecialist fully to understand. Nevertheless, our task is to write at the university level. Therefore, if a difficult or advanced piece of text ''can'' be written in a way to make it more accessible to educated nonspecialists, then it ''should'' be.
For usage of [[SI]] ("metric") units see the [http://www.physicstoday.org/guide/metric.html Physics Today] guide for metric practice.  


Scientists, business people, lawyers, and academics are famous for writing mumbo-jumbo that is decipherable only by people in their fields. But, as this is a ''general'' encyclopedia, not a single topic encyclopedia, is our obligation to "translate" the jargon of a specialized field, so far as is possible, into elegant English prose.
For physics oriented articles consult chapters III and IV of [http://forms.aps.org/author/styleguide.pdf The American Physical Society Style Guide]. (Pdf).


Even if an article concerns some very abstruse topic, the details of which no one but specialists can be expected to understand, ''if'' there is a way to introduce some fundamental aspect of the topic that is accessible to nonspecialists, then the article should begin with such an introduction. For example, the details of [[quantum mechanics]] cannot be expected to be understandable by anyone but physicists, but there are certain experiments and analogies that can be used to introduce the topic: if such explanatory devices, accessible to the layperson, are ready to hand, then we should make use of them.
=== Lists ===
Main articles should not be a list of topics (even if annotated). The appropriate place for such material is either the Related Articles subpage or a Catalogs subpage. Such lists are not collected using [[CZ:Categories|categories]] (Categories are only used for administrative purposes).


=== Write lively prose, not "encyclopedese" ===
=== Write lively prose, not "encyclopedese" ===
Writing an encyclopedia brings out a tendency in some writers to make prose dull--perhaps  the influence of boring encyclopedia articles we read as children.  But we can, and should, give our prose personality. Many writers today have taken William Strunk's pithy injunction, [http://www.bartleby.com/141/strunk5.html#13 "Omit needless words,"] to heart.  Tightening up flabby verbiage is one of the most ''needful'' improvements we can make, '''but''' we must not denature our prose entirely: we want our writing to be readable, not encyclopedese.


The task of writing an encyclopedia brings out a natural tendency in some writers to make prose dull--perhaps it is the influence of all those boring encyclopedia articles we read as children.  But our writing needn't be like that.  We can, and should, give our prose personality and punchiness.  (And others should be careful not to rewrite such prose so that it loses its personality!)
Another common stylistic rule would have us use simple Anglo-Saxon words rather than hifalutin, impressive-sounding words, '''but''' this does not mean that we should prefer a merely adequate word to a really apt word just because the apt word is a bit more obscure. Choose the familiar word rather than the obscure word, but the precise word rather than the loose word.
 
Many writers today have taken William Strunk's pithy injunction, [http://www.bartleby.com/141/strunk5.html#13 "Omit needless words,"] to heart.  When applying this often excellent advice to others' words, however, writers will sometimes dogmatically insist on omitting words the function of which they do not fully appreciate.  For instance, one might replace "It was Aristotle among the ancient Greek philosophers whose works are voluminous" with "Aristotle wrote voluminously," halving the number of words--surely a victory in the fight against needless words.  But the former formulation ''might'' be more apt: the idea is that many people know (or perhaps should know) that there was an ancient thinker who is famous for having voluminous works.  That thinker was Aristotle.  Strunk's advice is excellent, and tightening up flabby verbiage is one of the most ''needful'' improvements we can make.  We must simply not go so far as to denature our prose entirely: we want our writing to be readable, not encyclopedese.
 
Another common stylistic rule would have us use simple Anglo-Saxon words rather than hifalutin, impressive-sounding Latin words.  This is usually good advice too--except when it's not.  The tendency to ''over''simplify language results in many a dull textbook and encyclopedia.  We want our articles to be accessible, but this does not mean that we should prefer a merely adequate word to a really apt word, simply because the apt word is a bit more obscure.


=== Link copiously, but relevantly ===
=== Link copiously, but relevantly ===
One strength of a wiki-based encyclopedia is the ease with which articles can link to other articles.  Links permit serendipitous discoveries, and ''Citizendium'' encourages copious interlinking. But [[pronoun|it]] is [[possibility|possible]] to take [[demonstrative pronoun|this]] [[advice]] to an [[absurdism|absurd]] [[extremism|extreme]]--linking so many words that many ''inappropriate'' links are created, that distract rather than help. Remember that two consecutive links (of the same color) will run together as if they were one; it may be better to reword so the links are separated by a non-link word.


One of the great strengths of using a wiki to develop an encyclopedia is the tremendous ease with which articles can link to other articles.  Links invite knowledge-seekers to follow their interests wherever they are go.  Links permit serendipitous discoveries, which is, after all, one of the great attractions of reference works generally.  So, ''without'' these links, the product as a whole is considerably less interesting.  Therefore, the ''Citizendium'' officially encourages copious interlinking of articles.
A general rule is:
 
:'''If our target audience would find that the linked article illuminates the present article, then we should link to it.'''
But [[pronoun|it]] is [[possibility|possible]] to take [[demonstrative pronoun|this]] [[advice]] to an [[absurdism|absurd]] [[extremism|extreme]]--linking so many words that many ''inappropriate'' links are created, links that distract rather than help.
 
Therefore, there is a general (not infallible) rule for determining whether a link is appropriate or helpful:
 
:'''If our target audience would find that the article linked-to illuminates the present article, then we should link to it.'''
 
Someone looking at an article about [[duck]]s might well find articles on anything bird-related, such as [[wing]]s, [[quack]]ing, and [[feeding ecology]] illuminating.  Similarly, other things that are related only in an ancillary way, such as [[park]]s and [[hunting]], shed light on the topic of ducks.  But in passing, the article might use completely unrelated, common English words, such as "argument" or "landscape."  Someone reading about ducks needs only to know the meaning of these words; if one learns all there is to know about arguments or landscapes, one does not learn much of anything that helps to understand the article about ducks.
 
If, however, the "duck" article happened to contain the phrase "The War of the Roses," then despite the fact that that topic has little to do with ducks, we should nevertheless link the phrase--[[The War of the Roses]]--simply because it is unknown to a significant part of our target audience.  Note that this is not inconsistent with the rule: our target audience would find the "War of the Roses" article illuminating, not because it sheds light on ducks, but because it clarifies the meaning of a perhaps obscure phrase that just happens to be used in the "duck" article.
 
=== Do link to nonexistent articles ===
 
In order to build out the ''Citizendium,'' it is very important to add links--despite their "ugliness"--to articles that do not yet exist.  Such links invite people to build out the ''Citizendium,'' by making it clear to everyone that an article is needed.  Links that lead nowhere, moreover, help us to gauge what articles are most needed: see [[Special:Wantedpages|Wanted Pages]] (linked on the left under toolbox > Special pages).
 
=== Link the first use only ===


Link only the first use of a word or phrase, not every use--unless the word or phrase is ''particularly'' relevant to the ''specific'' point being made.  Thus, for example, the article about [[Abraham Lincoln]] might mention (and link to) the [[Emancipation Proclamation]] in its introductory section, but it should also link the phrase when it comes to the section about the Proclamation itself.
It is important to add links to articles that do not yet exist -these help us see what articles are most needed: see [[Special:Wantedpages|Wanted Pages]] (linked on the left under toolbox > Special pages).  


=== Don't use external links within the article body ===
Link only the first use of a word or phrase, not every use--unless the word is ''particularly'' relevant to the point. Thus, the article about [[Abraham Lincoln]] might mention (and link to) the [[Emancipation Proclamation]] in its opening section, and also in the section about the Proclamation itself.


Please don't use external links within the article body. Place them either in a footnote (if a particular page or section is relevant), in an "External links" section (if the material lives only online), or in a "Further reading" section (if the material is published, but also available online).
=== Quotations ===
In general, avoid quotations longer than one sentence, and do not use ''many'' quotations in any one article. Quotations should not be used to “make an argument”; an argument is made by logic and reason, not by authority, and if a quote is used to support an argument by showing that important people agree with the point, then this is a misuse. However if notable people are identified with a particular argument, then it would be reasonable to quote them. For example, [[Richard Dawkins]] is a vocal proponent of [[evolution|Darwinism]]—it should not be presented as an argument for Darwinism that its proponents include Richard Dawkins, but as he has contributed extensively to the debate, to quote him would be a reasonable way of illustrating a section that describes his arguments.  


It is hard to deny that external links (i.e., links to pages on external websites) within the body of an article would be useful, particularly if we lack an article about something.  But it is important to understand the function of red links in the ''Citizendium.''  Articles that have red links are unquestionably uglier, and not just because of a different color, but because red means nothing is available to view. However, this ugly state of unavailability is an itch that project members work to scratch; it is also an invitation to new contributors to join us in order to "turn the red links blue."  If we were simply to use links to external articles, there would be rather less incentive--perhaps much less incentive--to start our own articles.  
Valid uses of quotes include (in biographical sections) to illustrate a person’s views; (in literature articles) to exemplify an author’s style; and (in many articles) to add colour and interest to an article. Be aware that, in some articles, using quotes can introduce a bias. Choose them with care, and consider redressing any bias by annotations, or by balancing quotes from other viewpoints.


=== No long quotations ===
=== Conversions ===
There is one central [[Template:Convert|conversion template]], {{tl|Convert}}. This can be used to  convert between two units of measurement. To use it, write it out as you would speak the conversion. For example "Convert 10 inches to centimetres" would be written <nowiki>"{{Convert|10|in|cm}}"</nowiki> and would display as {{Convert|10|in|cm}}.


As a general rule, we should not use quotations that are longer than one sentence, and we should not use ''many'' quotations in any one article. The purpose of a quotation is typically to illustrate or support some point. Quotations are, therefore, texts that ''support'' the main text, which the ''Citizendium'' writes.
More powerful features for individual conversions are found on individual templates.
Each has additional parameters that determine such things as abbreviation, spelling, ranges, two dimensional, three dimensional, and whether or not to wiki-link the units of measurement.
An example would be {{tl|In to Cm}}. These should only be used if {{tl|Convert}} does not support the feature you need.


There are at least two main reasons for this policy against many and long quotations.
A full list is at [[:Category:Conversion templates]]


First, such quotations prevent collaboration on the substance of the text (quotations are uneditable).  It is inherently biased to have an extended quote that speaks ''for'' the ''Citizendium,'' since in that case the ''Citizendium'' is made to endorse a whole series of points that are only that source's idiosyncratic views.  Second, the practice of adding a long quotation cannot be generalized.  If we have a long quotation that supports one point, why should we not have long quotations that support ''every'' point?  There is a vast universe of books and other potentially supporting verbiage.  We could find long quotations for ''everything,'' if we wanted to.  Therefore, unless there is some particularly good reason to use a quotation beyond one sentence, don't do it; summarize.


The exceptions will, perhaps, be in cases where texts themselves are the ''primary'' subject of an article.  Even in this case, extended quotations are to be used sparingly and only with excellent justification.
<center>'''This is a policy summary.  [[CZ:Article mechanics Complete|The complete document is here]].'''</center>


== For further reading ==
{{Content Policy}}
[[CZ:Sage_advice_on_writing_CZ_articles|Sage advice on writing CZ articles]].
[[Category:Policies]]

Latest revision as of 16:02, 5 March 2024

This is a summary of The complete document here.

See also content policy.

Citizendium aims to build a body of articles that introduce their topics in an accessible, yet authoritative, way. An article is not a mere summary or list of information, but a connected piece of prose, meant to be read all the way through. Articles must be selective in what they present, but need not be brief; they should say what they need to as clearly as possible, in a concise and interesting way.

Opening section

The opening section should always be introductory, so the heading "Introduction" is unnecessary. The first paragraph usually begins with a definition, and we bold the title of the article in the first sentence, e.g.: "Philosophy is an abstract, intellectual discourse..." The first paragraph should contain a concise and neutral answer to "Why is this topic important (or interesting)?" If the topic is a person, say what the person is best known for; if an event, summarize its impact; if a place, describe what makes it notable. The rest of the opening section should give the background needed for understanding the rest of the article. The opening section can be a ‘’summary’’ of the article, but a brief outline of the article structure may be better if the article is very long.

The article body

Generally, articles need a plan that lends coherence and flow and invites readers to keep reading. A task of editors is to help plan articles, and this may be discussed on the Talk page. Generally, major achievements of individuals should be presented before minor ones; the basic tenets of a theory before derivative ones; and earlier events before later ones.

Section titles

Section headings help both readers and authors, but too many can be ugly and distracting. A well-organized narrative is this "Biology" article.

Standardized information

If there is to be an article about every species of snake, it is convenient to have a standard structure. When beginning an article, authors should check articles on closely related themes to see if a standard structure has already been established by others. Citizendium workgroups will ultimately settle on any such standard practices.

Citations

See Help:Citation style. We expect citations in about the same quantity as in academic encyclopedias. Citations are not usually needed for information that is common knowledge among experts. But the following categories of claims generally do need citation:

  • direct quotations
  • claims with unique sources (such as survey results, or the finding of a particular paper)
  • implausible-sounding but well-established claims
  • claims central to the article

Wherever possible, give an online link for any reference, at least to the abstract (via, for example, a PubMed reference.)

Rather than use several references in one sentence, it may be better to include several sources in one citation.

It is important to give full citation credit to imported illustrations, where for example these are imported from open-access journals.

Definition

See CZ:Definitions. Every page should have a subpage/Definition that only contains a short sentence explaining the topic of the page:

  • Maximum one sentence (no more than 30 words/150 characters, ignoring formatting characters).
  • Don't include the term defined in the definition itself.
  • Start the text with a capital letter and end with a period. (Use a semicolon, if necessary, in between, but no period.)

This definition is mainly used on the /Related Pages subpage where

{{r|number}} and {{r|no number}}

produce

If there is a main page, but no /Metadata page (e.g., if the page is a redirect), the template shows the link in boldface. A special case of this is a lemma article, which is an article that has a main page containing only the {{subpages}} template. In this case, the /Definition is transcluded to the page:

  • Foo lemma [r]: This example of a lemma has only a definition page and an article page with the subpages template. The article transcludes the text from the definition page. The link to the article, when using the R template is shown in black to indicate it has no more content that the definition which can already be seen. [e]

A definition intended for a lemma article may be longer than a "normal" definition. Lemma articles may have Related Articles, Bibliography and External Links subpages, which must not have the {{subpages}} template. At any time, a lemma article may be converted to a regular article; at that point, part of a long definition usually will move to the main page.

Metadata

See CZ:Article structure#Metadata

Organizational and technical information related to a page is stored on a special template page Template:ArticleName/Metadata: Title, title for alphabetization, workgroups, status, approval data, etc. It also contains the workgroup categories. (Please note that categories are only used for administrative purposes.)

Subpages

Factual material, where there is no real narrative flow, may be best presented in subpages. The standard subpages will always include:

Related articles subpage

This connects each article with related articles and offers greater insight into the underlying conceptual structure of the encyclopedia. Related Articles subpages generally are organized into a few Parent Topics, which are more general topics within which the current article is located; Subtopics, which are aspects of the main topic worth separate discussion; and Related Topics are "close tangents" which take the discussion off in new directions. The article on World War I includes Parent Topics on War and Nationalism, Subtopics include famous battles such as Gallipoli and the Somme, and Related Articles include Trench warfare and Mustard gas.

Bibliography subpage

This is an annotated bibliography: books, articles and other material that are important and useful, clarifying why an item is listed ("one of the most commonly used texts in this field"; "the paper which originally defined the concept"). For example, historical topics may list and annotate the leading sources for information on a topic, and articles about authors may list their major works. If an item is available online, the annotation should provide the link. (Here are the citation templates.) How to write annotations is discussed by the Library of Congress publication Creating an Annotation.

Articles may also have a "Suggested reading" section at the end of the main article that presents 5-10 publications suitable for beginners, especially if they are on the web.

External links subpage

See CZ:External Links

External links should be neutrally annotated. Links to external websites should not be placed within articles but in footnotes. Link words and phrases to Citizendium articles rather than external sources of information --even if we still lack an article on the subject. We have rules against self-promotion (policy on topic informants), and contributors should not link to websites that they manage, unless it is very evident that the website is a leading and reliable source of information.

Optional subpages

See list of optional subpages

Many other subpages may be included; the current list of subpages includes Works, Discography, Filmography, Catalogs, Timelines, Gallery (Images), Audio and Video pages, Computer Code, Tutorials, Student-level discussions, Signed Article, Function, Addendum, Debate Guide, Advanced and Recipes.
There are also some article-specific subpages (for certain topics) which are not yet fully acknowledged.
Please note Categories are used for administrative purposes (workgroups, etc.) only. Lists of topics are compiled on appropriate /Catalogs subpages.

Miscellaneous style guidelines

See also Sage advice on writing CZ articles.

Craft articles for maximum readability. Many topics may be impossible for a non-specialist fully to understand, but if an advanced piece of text can be written to make it more accessible to nonspecialists, then it should be. Professionals are often accused of writing jargon that is decipherable only by people in their fields; our task is to "translate" the jargon into elegant prose.

Grammar, spelling, punctuation, and usage

Strunk and White's Elements of Style is useful; the first edition is available here. For American English, please consult The Chicago Manual of Style for matters of formatting, punctuation, etc. and Garner's Dictionary of American English Usage for issues of usage. For British English, consult Fowler's Modern English Usage.

For usage of SI ("metric") units see the Physics Today guide for metric practice.

For physics oriented articles consult chapters III and IV of The American Physical Society Style Guide. (Pdf).

Lists

Main articles should not be a list of topics (even if annotated). The appropriate place for such material is either the Related Articles subpage or a Catalogs subpage. Such lists are not collected using categories (Categories are only used for administrative purposes).

Write lively prose, not "encyclopedese"

Writing an encyclopedia brings out a tendency in some writers to make prose dull--perhaps the influence of boring encyclopedia articles we read as children. But we can, and should, give our prose personality. Many writers today have taken William Strunk's pithy injunction, "Omit needless words," to heart. Tightening up flabby verbiage is one of the most needful improvements we can make, but we must not denature our prose entirely: we want our writing to be readable, not encyclopedese.

Another common stylistic rule would have us use simple Anglo-Saxon words rather than hifalutin, impressive-sounding words, but this does not mean that we should prefer a merely adequate word to a really apt word just because the apt word is a bit more obscure. Choose the familiar word rather than the obscure word, but the precise word rather than the loose word.

Link copiously, but relevantly

One strength of a wiki-based encyclopedia is the ease with which articles can link to other articles. Links permit serendipitous discoveries, and Citizendium encourages copious interlinking. But it is possible to take this advice to an absurd extreme--linking so many words that many inappropriate links are created, that distract rather than help. Remember that two consecutive links (of the same color) will run together as if they were one; it may be better to reword so the links are separated by a non-link word.

A general rule is:

If our target audience would find that the linked article illuminates the present article, then we should link to it.

It is important to add links to articles that do not yet exist -these help us see what articles are most needed: see Wanted Pages (linked on the left under toolbox > Special pages).

Link only the first use of a word or phrase, not every use--unless the word is particularly relevant to the point. Thus, the article about Abraham Lincoln might mention (and link to) the Emancipation Proclamation in its opening section, and also in the section about the Proclamation itself.

Quotations

In general, avoid quotations longer than one sentence, and do not use many quotations in any one article. Quotations should not be used to “make an argument”; an argument is made by logic and reason, not by authority, and if a quote is used to support an argument by showing that important people agree with the point, then this is a misuse. However if notable people are identified with a particular argument, then it would be reasonable to quote them. For example, Richard Dawkins is a vocal proponent of Darwinism—it should not be presented as an argument for Darwinism that its proponents include Richard Dawkins, but as he has contributed extensively to the debate, to quote him would be a reasonable way of illustrating a section that describes his arguments.

Valid uses of quotes include (in biographical sections) to illustrate a person’s views; (in literature articles) to exemplify an author’s style; and (in many articles) to add colour and interest to an article. Be aware that, in some articles, using quotes can introduce a bias. Choose them with care, and consider redressing any bias by annotations, or by balancing quotes from other viewpoints.

Conversions

There is one central conversion template, {{Convert}}. This can be used to convert between two units of measurement. To use it, write it out as you would speak the conversion. For example "Convert 10 inches to centimetres" would be written "{{Convert|10|in|cm}}" and would display as 10 in (25.4 cm).

More powerful features for individual conversions are found on individual templates. Each has additional parameters that determine such things as abbreviation, spelling, ranges, two dimensional, three dimensional, and whether or not to wiki-link the units of measurement. An example would be {{In to Cm}}. These should only be used if {{Convert}} does not support the feature you need.

A full list is at Category:Conversion templates


This is a policy summary. The complete document is here.


Citizendium Content Policy
Approval Standards | Article Mechanics | Subpages | Importing material from other sources | Citable articles

|width=10% align=center style="background:#F5F5F5"|  |}

Retrieved from "https://citizendium.org/wiki/index.php?title=CZ:Article_mechanics&oldid=924892"