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

From Discourse DB
Jump to navigation Jump to search
(New tutorial page)
 
(added quick and full versions)
Line 1: Line 1:
Adding content in Discourse DB is fairly easy; it requires mostly some thinking about naming and structure, and very little technical knowledge. All the data on Discourse DB is stored in a database, and is represented internally by a set of semantic relations and attributes; thanks to the power of templates, though, you don't have to worry about any of this. Every piece of content added can be done through templates, which hide away all the technical details and require only deciding what the value of each field should be.
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.


Before we go any further, please note that '''you do not have to registered in order to add content to the site'''. 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.


We'll use an example to illustrate the content-adding process.
=The Quick Version=


==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 18: Line 17:
:...
:...


And on it goes. You would like to include this column as an opinion item in Discourse DB.
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 on the left side of the page, and enter the name of the op-ed item in the input box on the page.  You will then see a page with the following content.


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: it has to comment on some policy matter, and 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. This column certainly fits the criterion of subject matter, since it takes a strong stand on a proposed government action. You look up ''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.
 
<pre>
{{item
|author=
|source=
|date=
|url=
|quote="quote here"
}}
 
{{opinion|TOPIC|POSITION|for, against, OR mixed}}
</pre>
 
You should fill it out to look like this: (Note that consistency in spelling and capitalization is very important)
 
<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 is saved in the database.  That's it!  For more details on what's going on, continue reading below.
 
=The Full Version=
 
==Adding op-ed items==
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: it has to comment on some policy matter, and 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. This column certainly fits the criterion of subject matter, since it takes a strong stand on a proposed government action. You look up ''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.

Revision as of 22:39, September 25, 2006

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.

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

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
October 10, 2006
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, 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 on the left side of the page, and enter the name of the op-ed item in the input box on the page. You will then see a page with the following content.


{{item
|author=
|source=
|date=
|url=
|quote="quote here"
}}

{{opinion|TOPIC|POSITION|for, against, OR mixed}}

You should fill it out to look like this: (Note that consistency in spelling and capitalization is very important)

{{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}}

When you click 'Save page', the new item is saved in the database. That's it! For more details on what's going on, continue reading below.

The Full Version

Adding op-ed items

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: it has to comment on some policy matter, and 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. This column certainly fits the criterion of subject matter, since it takes a strong stand on a proposed government action. You look up 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.

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 "Enter". 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:

{{item
|author=
|source=
|date=
|url=
|quote="quote here"
}}

{{opinion|TOPIC|POSITION|for, against, OR mixed}}

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 field from the next. We can see that the templates are structured differently: in the first one, each field includes the variable name itself, and you are meant to put the value for the field after each equals sign ("="). In the second one, the field name 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 on the page: that's because it's already there as part of the page's URL.)

The item template

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 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.

Now, there's no need at this point to also fill in the "opinion" template; you could simply delete that template from the page, 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 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:

{{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}}

If you then hit "Save page", you're done.

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.