Difference between revisions of "Help:How to add content"

From Discourse DB
Jump to navigation Jump to search
(Various small improvements)
(Somewhat of an overhaul for new item-adding approach)
Line 1: Line 1:
Adding content in Discourse DB is easy, but it is slightly different from Wikipedia and other websites. This page should help explain things.  First we present the quick version, for those who simply want to add an op-ed item to the database.  Then we present the full version, to answer any little questions that pop up, and to explain how to create new topics and positions.
Adding content in Discourse DB is easy, but it is slightly different from Wikipedia and other wiki sites. This page should help explain things.


Remember, '''you do not have to register in order to contribute'''. You can add pages and edit all content on the site even without being registered. Still, we recommend registering (a very quick process) if you're planning to do any significant editing; it's easier for everyone to see your editing history, and to communicate with you if need be.
Remember, '''you do not have to register in order to contribute'''. You can add pages and edit all content on the site even without being registered. Still, we recommend registering (a very quick process) if you're planning to do any significant editing; it's easier for everyone to see your editing history, and to communicate with you if need be.


=The Quick Version=
==Items==
===Adding an item===


Let's say you're reading your favorite newspaper, ''The United States Times'' (this is not a real newspaper), and you spot the following column:
Let's say you're reading your favorite newspaper, ''The United States Times'' (this is not a real newspaper), and you spot the following column:
Line 9: Line 10:
:'''Free ice cream? No thanks'''
:'''Free ice cream? No thanks'''
:'''By Christopher D. Example'''
:'''By Christopher D. Example'''
:'''October 10, 2006'''
:'''January 10, 2007'''


:Of all the bad ideas coming out of our nation's leadership lately, the Free Ice Cream Fridays Act has to be among the worst. The bill, which is right now being voted on in the House, would organize the handing-out of free ice cream every Friday at 5. Sure, it sounds appealing: who doesn't want a nice dessert after a hard week at the office, or at school? But what doesn't get mentioned is the cost to the economy, and the lost productivity. I know at 5, I'll be running out the door to get my scoop, instead of working on whatever column I should be writing. This refreshing but unnecessary work-break brought to you by the American taxpayer.
:Of all the bad ideas coming out of our nation's leadership lately, the Free Ice Cream Fridays Act has to be among the worst. The bill, which is right now being voted on in the House, would organize the handing-out of free ice cream every Friday at 5. Sure, it sounds appealing: who doesn't want a nice dessert after a hard week at the office, or at school? But what doesn't get mentioned is the cost to the economy, and the lost productivity. I know at 5, I'll be running out the door to get my scoop, instead of working on whatever column I should be writing. This refreshing but unnecessary work-break brought to you by the American taxpayer.
Line 17: Line 18:
:...
:...


To add this item, you should first make sure it is appropriate for the site, and then make sure it has not been added before.  You can read more about those steps below.  To simply add the new item, click on the '[[Add content]]' link here or on the left side of the page, and enter the name of the op-ed item in the "New item" input box on the page. You will then see a page with the following content:
To add this item, you should first make sure it is appropriate for the site, then make sure it has not been added before.  You can read more about those steps below.  To simply add the new item, click on the '[http://discoursedb.org/add_item.php Add an item]' link here or on the left side of the page, and enter into the form the following values:


<pre>
:'''Title:''' Free ice cream? No thanks
{{item
:'''Author:''' Christopher D. Example
|author=
:'''Source:''' The United States Times
|source=
:'''Date:''' January 10, 2007
|date=
:'''URL:''' http://www.theunitedstatestimes.com/opinions/example/9DJF7QO1.html
|url=
:'''Quote:''' But what doesn't get mentioned is the cost to the economy, and the lost productivity. I know at 5, I'll be running out the door to get my scoop, instead of working on whatever column I should be writing.
|quote="quote here"
}}
 
{{opinion|TOPIC|POSITION|for, against, OR mixed}}
</pre>
 
You should fill it out to look like this: (note that it's very important to match the spelling and capitalization of what's already on the site)
 
<pre>
{{item
|author=Christopher D. Example
|source=The United States Times
|date=October 10, 2006
|url=http://www.theunitedstatestimes.com/opinions/example/9DJF7QO1.html
|quote="But what doesn't get mentioned is the cost to the economy, and the lost productivity.
I know at 5, I'll be running out the door to get my scoop, instead of working on whatever column
I should be writing."
}}
 
{{opinion|Free Ice Cream Fridays Act|Act should be passed|against}}
</pre>


When you click 'Save page', the new item, and the opinion it takes, are saved in the database. That's it! For more details on what's going on, continue reading below.
:'''Opinion:'''
:'''Topic:''' Free Ice Cream Fridays Act
:'''Position:''' Act should be passed
:Against


=The Full Version=
When you click 'Preview', you'll be taken to the preview page for that item. If everything looks alright, just hit "Save page" to enter that item in the database. That's it! For more details on what's going on, continue reading below.


==Adding op-ed items==
===Establishing notability===
OK, you have found an editorial you would like to include, as described above.  The first thing to ask is, is this a notable opinion item? In order to be included in Discourse DB, the column has to pass two criteria: (1) it has to comment on some policy matter, and (2) it has to have been published in a notable source; you can find the full requirements for a notable source at [[Help:Sources]], but basically that currently means that it has to have a circulation of at least 50,000, if it's a print publication, or get at least 50,000 unique visitors a month, if it's an online publication. The example column above certainly fits the criterion of subject matter, since it takes a strong stand on a proposed government action. You do a web search on ''The United States Times'' and you see that it was recently audited as having a daily circulation of 90,000, so this item fits the notable-source criterion as well.
OK, you have found an editorial you would like to include, as described above.  The first thing to ask is, is this a notable opinion item? In order to be included in Discourse DB, the column has to pass two criteria: (1) it has to comment on some policy matter, and (2) it has to have been published in a notable source; you can find the full requirements for a notable source at [[Help:Sources]], but basically that currently means that it has to have a circulation of at least 50,000, if it's a print publication, or get at least 50,000 unique visitors a month, if it's an online publication. The example column above certainly fits the criterion of subject matter, since it takes a strong stand on a proposed government action. You do a web search on ''The United States Times'' and you see that it was recently audited as having a daily circulation of 90,000, so this item fits the notable-source criterion as well.


The next step is to make sure that this item hasn't already been included in Discourse DB. The easiest way is to search the site for the author or publication name (using the search form in the sidebar), and look through the search results. You can also search by the column title, though sometimes columns are syndicated and will show up in more than one publication, under different titles.
The next step is to make sure that this item hasn't already been included in Discourse DB. The easiest way is to search the site for the author or publication name (using the search form in the sidebar), and look through the search results. You can also search by the column title, though sometimes columns are syndicated and will show up in more than one publication, under different titles.


Assuming you can't find this column on the site, you can go straight to adding it. If you go to '[[Add content]]', you'll see a form for adding a new item. Enter the title of the column in the text field, and hit "Create". This will not create the item; instead, it will lead you to a page with the text you entered as the page title, and the following content:
===The fields===
 
<pre>
{{item
|author=
|source=
|date=
|url=
|quote="quote here"
}}
 
{{opinion|TOPIC|POSITION|for, against, OR mixed}}
</pre>
 
What we have here are two templates: the "item" template and the "opinion" template. The first gives identifying information on the opinion item that is the subject of this page; the second gives a description of an opinion argued by this item.
 
If we look at the structure of each template, the double-brackets ("{{") are the declaration of a template, and the first word that appears ("item" and "opinion", here) state the name of the template to be used. Pipes ("|") separate one piece of data from the next. We can see that the templates are structured differently: in the first one, each piece of the data includes the name of the data, and you are meant to put the value after each equals sign ("="). In the second one, the name of that data is not included; the words "TOPIC" and "POSITION" are merely a convenience to remind you of what goes where, and are meant to be replaced with the real value by you, the contributor.
 
(Note that the actual name of the item is nowhere to be found within either template: that's because it's already there as part of the page's URL, and it appears in the page's title.)
 
===The item template===
:''For more information, see [[Help:Items]]''
:''For more information, see [[Help:Items]]''
So, let's populate the item template first: the "url" and "date" fields are fairly straightforward; the parser will be able to understand the date in a variety of formats. For the quote, you should pick a one-to-five-sentence snippet, from the body of the column itself, that captures the point of view and tone of the column. Feel free to look through other items in Discourse DB for a sense of quoting style. As to source and author, there may be some ambiguity here - should it be "United States Times" or "The United States Times"? Should the author be "Christopher D. Example" or "Christopher Example" ? Or "Chris Example"? We suggest you search on the site to see if this source and author have been cited before, and, if so, see what name was used for them. If there are no previous cites, you should look on [http://en.wikipedia.org Wikipedia] to see how they are referred to there; general Discourse DB style is to copy Wikipedia's naming conventions whenever possible. If the author and/or source don't appear in either Discourse DB or Wikipedia, go with whatever name you think makes the most sense.
:''For more information, see [[Help:Opinions]]''
:''For more information, see [[Help:Topics]]''
:''For more information, see [[Help:Positions]]''


Now, there's no need at this point to also fill in the "opinion" template; you could simply delete that template from the page, scroll down and hit "Save page", and be done with it. But it is possible (and in fact it's recommended) that you also indicate the opinion(s) that this column is taking, by using one or more "opinion" templates. In this case, there's just one opinion: that the Free Ice Cream Fridays Act should not be passed.
The "URL" and "date" fields are fairly straightforward. For the quote, you should pick a one-to-five-sentence snippet, from the body of the column itself, that captures the point of view and tone of the column. Feel free to look through other items in Discourse DB for a sense of quoting style. As to source and author, there may be some ambiguity here - should it be "United States Times" or "The United States Times"? Should the author be "Christopher D. Example" or "Christopher Example" ? Or "Chris Example"? Thankfully, the auto-complete feature in the "Add item" form will help fill in values that already appear in the database. If there are no previous entries for this author or source, you should look on [http://en.wikipedia.org Wikipedia] to see how they are referred to there; general Discourse DB style is to copy Wikipedia's naming conventions whenever possible. If the author and/or source don't appear in either Discourse DB or Wikipedia, go with whatever name you think makes the most sense.
 
===The opinion template===
:''For more information, see [[Help:Opinions]]''
Filling in the "opinion" template requires having a ''topic'' and ''position'' to cover this stance; see [[Help:Topics]] and [[Help:Positions]] for an explanation of these two concepts. To decide on the topic name, you should use the same methodology described for sources: first look it up in Discourse DB, then, if that fails, on Wikipedia. For the position name, if it doesn't already exist in Discourse DB, try to match the style of existing position names. So you could enter the entire item, including the opinion it takes, as:
<pre>
{{item
|author=Christopher D. Example
|source=The United States Times
|date=October 10, 2006
|url=http://www.theunitedstatestimes.com/opinions/example/9DJF7QO1.html
|quote="But what doesn't get mentioned is the cost to the economy, and the lost productivity.
I know at 5, I'll be running out the door to get my scoop, instead of working on whatever column
I should be writing."
}}


{{opinion|Free Ice Cream Fridays Act|Act should be passed|against}}
The "topic" and "position" fields are both optional, but to add them in, see [[Help:Topics]] and [[Help:Positions]] for an explanation of these two concepts. To decide on the topic name, you should use the same methodology described for sources and authors: first, see if the auto-complete feature offers a reasonable possibility, then, if that fails, on Wikipedia. For the position name, if it doesn't already exist in Discourse DB, try to match the style of existing position names.
</pre>
If you then hit "Save page", you're done.


==Adding a topic==
==Adding a topic==
Line 104: Line 53:
Once you've added the item, you may see a variety of red links on that item's page, for some combination of the topic, position, author and source; a red link means that no page currently exists in Discourse DB for that title. To create the page for a topic, and turn its red link blue, you need to fill it in with a "topic" template. This template, when blank, looks like the following:
Once you've added the item, you may see a variety of red links on that item's page, for some combination of the topic, position, author and source; a red link means that no page currently exists in Discourse DB for that title. To create the page for a topic, and turn its red link blue, you need to fill it in with a "topic" template. This template, when blank, looks like the following:
<pre>
<pre>
{{topic|
{{topic
start date=|
|start date=
end date=
|end date=
}}
}}
</pre>
</pre>
Line 122: Line 71:
{{wikipedia}}
{{wikipedia}}


{{topic|
{{topic
start date=October 2, 2006|
|start date=October 2, 2006
end date=
|end date=
}}
}}


Line 146: Line 95:
{{wikipedia}}
{{wikipedia}}


{{source|
{{source
type=Newspaper
|type=Newspaper
circulation=90,000|
|circulation=90,000
country=United States|
|country=United States
language=English|
|language=English
url=http://www.theunitedstatestimes.com/
|url=http://www.theunitedstatestimes.com/
}}
}}
</pre>
</pre>
Line 162: Line 111:
{{wikipedia}}
{{wikipedia}}


{{author|
{{author
first name=Christopher|
|first name=Christopher
last name=Example|
|last name=Example
political affiliation=Moderate
|political affiliation=Moderate
}}
}}
</pre>
</pre>

Revision as of 16:59, December 27, 2006

Adding content in Discourse DB is easy, but it is slightly different from Wikipedia and other wiki sites. This page should help explain things.

Remember, you do not have to register in order to contribute. You can add pages and edit all content on the site even without being registered. Still, we recommend registering (a very quick process) if you're planning to do any significant editing; it's easier for everyone to see your editing history, and to communicate with you if need be.

Items

Adding an item

Let's say you're reading your favorite newspaper, The United States Times (this is not a real newspaper), and you spot the following column:

Free ice cream? No thanks
By Christopher D. Example
January 10, 2007
Of all the bad ideas coming out of our nation's leadership lately, the Free Ice Cream Fridays Act has to be among the worst. The bill, which is right now being voted on in the House, would organize the handing-out of free ice cream every Friday at 5. Sure, it sounds appealing: who doesn't want a nice dessert after a hard week at the office, or at school? But what doesn't get mentioned is the cost to the economy, and the lost productivity. I know at 5, I'll be running out the door to get my scoop, instead of working on whatever column I should be writing. This refreshing but unnecessary work-break brought to you by the American taxpayer.
That's not to mention all the logistical problems: I'm envisioning trucks that couldn't get to their destinations fast enough showing up with melted ice cream to a disappointed crowd. And what about lactose-intolerant people? As always, they get the worst deal of all. Calling it the "Free Frozen Desserts Friday Act" would have gone a long way to creating some basic fairness, but of course the geniuses in Washington would never have that much sense.
...

To add this item, you should first make sure it is appropriate for the site, then make sure it has not been added before. You can read more about those steps below. To simply add the new item, click on the 'Add an item' link here or on the left side of the page, and enter into the form the following values:

Title: Free ice cream? No thanks
Author: Christopher D. Example
Source: The United States Times
Date: January 10, 2007
URL: http://www.theunitedstatestimes.com/opinions/example/9DJF7QO1.html
Quote: But what doesn't get mentioned is the cost to the economy, and the lost productivity. I know at 5, I'll be running out the door to get my scoop, instead of working on whatever column I should be writing.
Opinion:
Topic: Free Ice Cream Fridays Act
Position: Act should be passed
Against

When you click 'Preview', you'll be taken to the preview page for that item. If everything looks alright, just hit "Save page" to enter that item in the database. That's it! For more details on what's going on, continue reading below.

Establishing notability

OK, you have found an editorial you would like to include, as described above. The first thing to ask is, is this a notable opinion item? In order to be included in Discourse DB, the column has to pass two criteria: (1) it has to comment on some policy matter, and (2) it has to have been published in a notable source; you can find the full requirements for a notable source at Help:Sources, but basically that currently means that it has to have a circulation of at least 50,000, if it's a print publication, or get at least 50,000 unique visitors a month, if it's an online publication. The example column above certainly fits the criterion of subject matter, since it takes a strong stand on a proposed government action. You do a web search on The United States Times and you see that it was recently audited as having a daily circulation of 90,000, so this item fits the notable-source criterion as well.

The next step is to make sure that this item hasn't already been included in Discourse DB. The easiest way is to search the site for the author or publication name (using the search form in the sidebar), and look through the search results. You can also search by the column title, though sometimes columns are syndicated and will show up in more than one publication, under different titles.

The fields

For more information, see Help:Items
For more information, see Help:Opinions
For more information, see Help:Topics
For more information, see Help:Positions

The "URL" and "date" fields are fairly straightforward. For the quote, you should pick a one-to-five-sentence snippet, from the body of the column itself, that captures the point of view and tone of the column. Feel free to look through other items in Discourse DB for a sense of quoting style. As to source and author, there may be some ambiguity here - should it be "United States Times" or "The United States Times"? Should the author be "Christopher D. Example" or "Christopher Example" ? Or "Chris Example"? Thankfully, the auto-complete feature in the "Add item" form will help fill in values that already appear in the database. If there are no previous entries for this author or source, you should look on Wikipedia to see how they are referred to there; general Discourse DB style is to copy Wikipedia's naming conventions whenever possible. If the author and/or source don't appear in either Discourse DB or Wikipedia, go with whatever name you think makes the most sense.

The "topic" and "position" fields are both optional, but to add them in, see Help:Topics and Help:Positions for an explanation of these two concepts. To decide on the topic name, you should use the same methodology described for sources and authors: first, see if the auto-complete feature offers a reasonable possibility, then, if that fails, on Wikipedia. For the position name, if it doesn't already exist in Discourse DB, try to match the style of existing position names.

Adding a topic

For more information, see Help:Topics

Once you've added the item, you may see a variety of red links on that item's page, for some combination of the topic, position, author and source; a red link means that no page currently exists in Discourse DB for that title. To create the page for a topic, and turn its red link blue, you need to fill it in with a "topic" template. This template, when blank, looks like the following:

{{topic
|start date=
|end date=
}}

The start date and end date are optional; they're meant to give a sense for the time frame for this topic. Some topics don't have a precise start and end date; others have one but not the other.

The topic page should also include some information to indicate to readers what is being discussed. The easiest way to do this is simply to include a link to the Wikipedia article on the same topic, if one exists. This can be done with the "wikipedia" template, which can be called either as

{{wikipedia}}

if this page has the same title as the Wikipedia page, or

{{wikipedia|PAGE_NAME}}

if the Wikipedia page has a different title. If there's no link-worthy page in Wikipedia, you can just include your own short description and a set of links.

It's also helpful to add the topic to one or more categories; you can see the current main list of categories at Main categories. This involves the very simple "category" tag; you can read how to add categories at the Wikimedia category help page.

So, putting all these together, you could create a page, named "Free Ice Cream Fridays Act", that looks like:

{{wikipedia}}

{{topic
|start date=October 2, 2006
|end date=
}}

[[Category:United States domestic politics]]

Hit "Save page", and you're done.

Adding a position

For more information, see Help:Positions

A position's page name will include the name of the topic it belongs to, for ease of use. The page name will read "TOPIC_NAME / POSITION_NAME" (note the spaces around the slash); in the case of the current example, it would be "Free Ice Cream Fridays Act / Act should be passed". The easiest way to create this page is to get there by clicking on the position's red link in the item page; that way the page name will already be perfectly formatted. Once you're there, you only have to type in:

{{position}}

And that's all.


Adding a source

For more information, see Help:Sources

Creating a source page involves the "source" template, and, as with topics, optionally the "wikipedia" template as well. See Help:Sources for more information on representing sources. The text to create the page for The United States Times could look like:

{{wikipedia}}

{{source
|type=Newspaper
|circulation=90,000
|country=United States
|language=English
|url=http://www.theunitedstatestimes.com/
}}

Adding an author

For more information, see Help:Authors

Creating an author page requires the "author" template, with three optional fields: the first name and last name (these are used for sorting and eventually will be used for searching as well), and political affiliation (the possible values for this field have not been standardized yet, so feel free to use any term here). As before, you can again optionally use the "wikipedia" template here. The text to create the page for Christopher D. Example could look like:

{{wikipedia}}

{{author
|first name=Christopher
|last name=Example
|political affiliation=Moderate
}}

Refreshing data

You may notice, after adding or modifying an opinion item, that the new item or modified data do not appear where they should appear, in a topic page, position page, author page, etc. That's most likely because the data that appears in that page is cached from before. You can make the new data appear by hitting the "refresh" tab at the top of this page.