Editing Project:Observatory Users Manual (section)

=== How to enter an Article (typical Observatory Article case) ===
 
==== I. Starting an Article ====
Ask your editor to start an Observatory Article page for you, including information via email (preferred) or [https://ed.observatory.wiki/Special:Contact/requestarticle request form]. Ask them to send you the link to work on. Then follow the instructions in Part II below. When you’re done editing your Article Draft, email your editor to let them know it’s ready for their review. Your editor will then review it and either give you feedback for revisions or Publish it.
 
Include the following in your email to your editor:
 
# [[Project:Style Guide/Editorial Process#Headline-Style Capitalization|Headline formatted in Observatory house style]]
# Area (if you don’t know, leave this out)
# Author(s)
# Source (i.e., affiliated organization/previous or partner publisher) if any
# Google Document of the Article (if you started one)
# Wikimedia Commons image (optional: can be done later, or your editor can pick for you)
# Any other information your editor should know about this Article (e.g., has this Article been previously Published?)
 
==== II. Filling in Observatory Article form fields ====
'''How to enter initial metadata (first Save):'''
 
===== Describe =====
 
====== Headline ======
Required. Follow the [[Project:Style Guide/Editorial Process#Headline|Headline guidelines in the Observatory Style Guide]]. And use headline-style capitalization rules from the [[Project:Style Guide/Editorial Process#Headline|Observatory Style Guide]].
 
====== Sort As ======
 
* This field determines the alphabetical order to display lists of Articles in some contexts, such as lists.
* Headlines that start with “The” or “A” or “An” or a punctuation mark (including a single open-quotation mark) need this field filled in with any of those elements removed.
** For example, for the Headline '''The Headline''', we would fill in the Sort As '''Headline, The'''.
 
* If there are special characters in the Headline, such as an accented letter such as é or â or ç, an umlaut such as ö or ï, or a character i like ı, etc., you should put the Headline in the Sort As field with the letter presented in its standard way.
** For example, for the Headline '''Café Culture of Italy''', we would fill in its Sort As '''Cafe Culture of Italy'''.
 
* The first letter must always be capitalized (it won’t display this way, but it will sort out of order if the first letter is lowercase).
* Leave this field blank if the Headline does not start with “The,” “A,” “An,” or a punctuation mark, ''and'' it does not contain special characters. The sorting order for Articles with blank Sort As fields will be determined by the Headline field.
 
====== Subtitle (Teaser) ======
Required. Follow the [[Project:Style Guide/Editorial Process#Teaser (i.e., Subtitle/Subheadline)|Teaser guidelines in the Observatory Style Guide]].
 
====== Editor’s Notes ======
This will appear at the bottom of Article for all readers (section is visible to the public too).
 
====== Author(s) ======
Fill in Author(s).
 
If a coauthor needs to be created and you don’t have access, ask your editor for help (provide your editor with their email address so we can onboard them).
 
====== Has audio version ======
Generally leave unchecked and let your editor handle.
 
====== Has video version ======
Generally leave unchecked and let your editor handle.
 
====== Cover Image ======
Let your editor handle for you.
 
====== Cover Image Page ======
Let your editor handle for you.
 
====== Suppress cover image display ======
Let your editor handle for you.
 
====== Suppress uploaded media caption ======
Let your editor handle for you.
 
====== Limit uploaded media width ======
Let your editor handle for you.
 
====== Section ======
A radio field with options for “Observatory” and “Classics.” Make sure the page was set to “Observatory” if you are entering a typical Article (“Classics” is only used for public domain content and will display fields in this form that don’t apply.) Ask your editor if you notice the wrong button was Pushed to make sure you’re working in the right namespace before continuing.
 
====== Source ======
Start typing in the Source of the Article, if there is one. For example, if it was originally produced by an affiliated organization, or if it was previously Published by another publication (including your organization or the Independent Media Institute or one of its projects: Earth Food Life Project, Economy for All Project, Human Bridges Project, Local Peace Economy Project, Our Schools Project, or Voting Booth Project). Select it as it starts to appear.
 
Articles have nothing in the Source field if the above does not apply.
 
If the organization name does not start to appear as you type, ask your editor if they would consider adding it to the Observatory as a Source. (In your request, please provide your editor with the organization’s website, contact email address of someone who can handle permissions requests at that organization, and their logo if you have it.)
 
====== Date first published ======
Enter the date of original publication if this is a reprint/embargoed, or today’s date if it’s original to the Observatory. If you only know the month and year, you may leave the exact day empty. An administrator may later change this to the date they Publish and Push.
 
====== Display date checkbox ======
Generally, always check this box, unless it’s extremely evergreen or your editor tells you not to. This will buy you some leeway on updating and give readers context (the date only appears at the bottom of the piece if this is checked, not up top or near the byline in the sidebar).
 
===== Explain =====
 
====== URL of the Google Doc source ======
Paste the URL of the Google Document where you worked on this Article with your editor.
 
====== Credit Line ======
Generally you might copy-paste from your previous Articles, unless there is a difference in the Source or permissions. Use the Credit Line from your Article template in most cases. Your editor can help with this.
 
===== Classify =====
 
====== Area ======
Required. You can only pick one Area per Article.
 
====== Tags ======
Enter a few keywords related to the Article, using headline-style capitalization and the [[Project:Style Guide/Editorial Process#Headline|Observatory Style Guide]].
 
Between 1 and 6 relevant tags is recommended, but you may use more. A maximum of 6 will be displayed in a random order on the page load. If you used more than 6 tags, “View More” button will cut the rest off.
 
===== Publish =====
 
====== Publish Checkbox ======
Your editor will handle this on your behalf after all revisions are complete.
 
===== Other =====
 
====== Bibliography ======
Many Articles leave this field blank.
 
If you have a bibliography to add at the bottom of your Article (in addition to/separate from the consideration of footnotes/endnotes), you may enter it here. Follow MLA style and the [[Project:Style Guide#Links and Footnotes for Observatory Articles/Dual Pub Plan|Observatory Style Guide]], and enter in the format of a numbered list. This field should benefit the public with additional sources to look up (it is not just used internally).
 
===== Article text =====
This will be your Article body. It is recommended to fill this in ''after'' your first Save. (Skip this field on your first Save and return to it later via “Edit with form” or “Edit” options.)
 
See Part III below on how to prepare your Article body for the Observatory site. If you don’t follow those instructions and try to copy-paste directly from the Google Document, you will create critical hyperlink and other formatting errors.
 
===== Save the Article page =====
 
====== Summary ======
Add a short statement summarizing changes you made (optional).
 
====== This is a minor edit checkbox ======
If it’s a minor edit, click to check this box.
 
You can change your default settings for this field in the top navigation menu’s “Edit” button→“Account Settings”→“Editing”→“Mark all edits minor by default” checkbox.
 
====== Watch this page ======
Check this box if you want to receive email notifications about changes to the Article. Leave it unchecked if not.
 
You can change your default settings for this field in the top navigation menu’s “Edit” button→“Account Settings”→“Watchlist”→Scroll down to “Watched pages” and check or uncheck the three checkboxes.
 
====== Save page (blue button) ======
Click this button when you’re done with this round of edits to the form. You can make further edits after your first or subsequent changes via “Edit with form” or “Edit” after this.
 
If you exit the page/tab/window in your browser or click the “Back” button in your browser, your changes may be lost.
 
Change your default settings to prompt a pop-up warning you if you will lose your work in “Edit” button→“Account Settings”→“Editing”→“Warn me when I leave an edit page with unsaved changes” checkbox.
 
'''Next, you will fill in the Article body.'''
 
==== III: Prepare your Article copy for the Observatory site ====
Consult with your editor on how to enter your Article. Most Observatory editors prefer you begin with a Google Document. Once it is finalized, '''you will need to convert the text so it is compatible with the Observatory software (MediaWiki/wikitext)'''. (In the rare case that you have prearranged to enter your copy directly into the Observatory site, you may skip Part III.)
 
If you have any questions or need help with the following conversion process, ask your editor for help.
 
===== PC: Follow the instructions for the free online converter: “Try Pandoc!” =====
Go to https://pandoc.org/try/.
 
Follow the ScribeHow instructions linked here: [https://scribehow.com/shared/Convert_from_a_Word_Doc_from_a_Google_Doc_to_Wikitext_Using_Free_Online_Pandoc_Converter__0XduCdANRqulMn1XPjKmRA “Convert from a Word Doc (from a Google Doc) to MediaWiki (wikitext) Using Free Online Pandoc Converter.”]
 
===== Mac: Software requirements =====
The first time you do this, you will need to set up some software. Get the Pandoc app and set up the Quick Action workflow:
 
# Install Pandoc, a file converter app, by going to https://pandoc.org/installing.html and clicking the big blue button “Download the Latest Installer.” Select the latest Mac file—it will end in “macOS.pkg.” (As of 1/8/25, available at [https://github.com/jgm/pandoc/releases/download/3.6.1/pandoc-3.6.1-x86_64-macOS.pkg pandoc-3.6.1-x86_64-macOS.pkg].) Go through the installation prompts and finish installing it.
# '''Install a Quick Action workflow''' to your computer to easily convert Article files into MediaWiki format in Finder with control+click and Pandoc:
## Download the customized Observatory workflow at this link: [https://drive.google.com/file/d/1TgIQdf8LP_mciyaEER2a6ao1vi1EwBDE/view?usp=sharing PandocConvertMediawiki.workflow.zip].
### Download all files at [https://drive.google.com/file/d/1TgIQdf8LP_mciyaEER2a6ao1vi1EwBDE/view?usp=sharing PandocConvertMediawiki.workflow.zip] (including subfolders).
### Unzip the file you downloaded.
### In Finder, open the unzipped .workflow file with the Automator app. Here’s how:
#### In Finder, find the file '''PandocConvertMediawiki.workflow''' that you just unzipped.
#### Double-click '''PandocConvertMediawiki.workflow'''.
#### Click “Install” on the dialog that has appeared.
#### Once installed, the “'''PandocConvertMediawiki'''” action will appear under the “Quick Actions” item of the context menu.
# '''Convert the Article file into MediaWiki format:''' These steps convert your Article body from Google Docs to a local Word Document or Open Office file to a TextEdit file containing the code of your Article formatted in MediaWiki language.
## In Google Docs, click “File”→“Download”→“Microsoft Word” to Save your Article as a local file (.docx or .doc). (OpenDocument format .odt is also acceptable if you use Open Office software.)
## In Finder, find your Article file and hover over it.
## Do not open the file—'''don’t double-click''' on it. Instead, press '''control+click''' (on a Mac keyboard; or right-click on a mouse) on the file to open a pop-up menu.
## At the bottom of the pop-up menu, hover over the option “Quick Actions” and then click on the “'''PandocConvertMediawiki'''” action.
## Your Article file will be converted to your new Article file in MediaWiki format at the top of your folder in Finder.
 
==== IV: Insert the MediaWiki code of your Article into the Observatory “Article text” (body) field of your Article Draft ====
Now you have your MediaWiki source code for the Article body ready to upload into the Observatory. Here’s what’s next:
 
# '''Open the new converted MediaWiki file''' of the Article body with your plaintext editor of choice ('''TextEdit''' or '''Notes''').
## Macs have the TextEdit app; PCs have Notes or a similar app.
### Mac users: If when you double-click the file it doesn’t open in TextEdit by default, then you can set it up:
#### Select the MediaWiki file, then open up a pop-up menu by pressing '''control+click→“Open With”→“Other'''.”
#### Change “Enable” field from “Recommended Applications” to “All Applications” and then look for TextEdit.
#### Double-click the TextEdit icon.
#### After this, TextEdit should appear on the “Open With” part of the above.
#### Recommended: You can make TextEdit the default app to open this kind of file now or later or never. If you made TextEdit default, it will open with TextEdit if you double-click a file of this type from now on.
# Copy the Article body (exclude frontmatter) part of the contents of the plaintext document and paste it into the “Article text” (Article body field) of your Draft on Observatory.wiki (whether you are in “Edit with form” or “Edit” mode, you need to be in “Edit Source” mode for “Source editing,” not Visual Editor).
# Check for errors in Visual Editor mode.
 
==== Tips for setting up the Article body ====
 
===== Best practices in Google Docs before converting files to MediaWiki =====
Keep the formatting of your Google Doc simple:
 
* No decorations or embedded images (those can come after you enter it on the Observatory).
* Structure elements/headings/subheadings need to be formatted as headers at the correct level (see [[Project:Observatory Users Manual#Follow these best practices for Headings and Subheadings|below]]).
* Carefully format your links and bold and italic text.
** Make sure you do not use the above-mentioned special formatting over blank spaces that appear before or after the text that you are italicizing, bolding, or hyperlinking.
** ''See: [[Project:Observatory Users Manual#Links|“Links” in the Glossary]].''
*Make a note of any block quotes as you create your Google Doc draft; you will manually convert paragraphs into blockquote formatting using the Header dropdown when you enter the piece on the Observatory.
 
====== Follow these best practices for headings and subheadings ======
 
* You can format the section titles within your Article body (headings/subheadings) at two points:
*# In the Google Doc: in the toolbar, change a heading from Normal text to Heading 1.
*#* Best practice: Keep '''section header formatting''' of Articles '''within the range of Heading 1→Heading 3''' when setting up sections of an Article in a Google Doc before converting.
*# After you convert via Pandoc to wikitext: change, using search and replace function, <nowiki>'''</nowiki>bolded line headings<nowiki>'''</nowiki> with three single apostrophes into <nowiki>==Wikitext Headings==</nowiki> with two equal signs around the line. If you have a subheading within a section, use three equal signs: <nowiki>===Wikitext Subheadings===</nowiki>.
* Wikitext guide: Don’t combine heading tags (equal signs) plus bold formatting—using just headline-style formatting will be sufficient, and bold formatting is redundant and discouraged.
**There is no need to make headings bold (with three straight apostrophes in the code); they are bold by default:
***'''Unnecessary:''' <nowiki>== '''Heading''' ==</nowiki>
***'''Good:''' <nowiki>== Heading ==</nowiki>
**The space between the heading text and the equal sign is optional. It doesn’t make a difference if it’s flush or if there is a space.
 
#Title is the page title—don’t use this except over your Article’s Headline. 
#*Use: It’s the title of the Article that appears at the top of the page. It can only be used once per Article.
#H1 is the highest level of an Article’s sections. You can use it for section titles like “Introduction” and “Background” or longer ones; it’s also not uncommon to only use this level throughout the Article body for all sections. Use H1 the way you normally use bold section headers in a Google Doc (if you format them as Heading 1 level in the Google Doc as opposed to simple bolding, they should automatically be converted during the Pandoc/workflow process the way you want them to look). 
#*Use: Many Articles will only use this level of heading as the deepest level of heading, and that’s fine; H2–H3 are not necessary, H4–H5 are inadvisable, and H6–H7 and beyond are not possible on the Observatory.
#*Table of contents (TOC) appearance: It appears flush-left in the table of contents on Article pages.
#* Short Articles that don’t have tables of contents might not even use this or any lower levels of section headers at all.
#* On the Observatory site, the menu calls this “Heading” (don’t confuse this with “Sub-heading 1,” which is actually H2, below!).
#H2 is the second-highest level of an Article’s sections. Use medium to sparingly.
#*Use: If you have subsections within H1 that need to appear in the TOC. (If it shouldn’t go in the TOC, just format the text as bold rather than using H2.)
#*TOC appearance: It appears one indentation to the right of H1.
#*On the Observatory site, the menu calls this “Sub-heading 1.”
#H3 is the third-highest level of an Article’s sections. Use sparingly.
#*Use: If you have subsections within H2 that need to appear in the TOC. (If it shouldn’t go in the TOC, just format the text as bold rather than using H3.)
#*TOC appearance: It appears one indentation to the right of H2 (at this point, things start to become indented so deeply that the TOC sidebar is going to be hard to read—that’s why our developer advises against using H3–H5, and the Observatory does not allow H6).
#*On the Observatory site, the menu calls this “Sub-heading 2.”
#<span style="color:#FF0000;">H4 is the fourth-highest level of an Article’s sections (one level deeper than H3). Don’t use</span>. Rather, just use the formatting you need to (bold, list, etc.) rather than formatting as a heading/subheading.
#<span style="color:#FF0000;">H5 is the fifth-highest level of an Article’s sections (one level deeper than H4). Don’t use</span>. Rather, just use the formatting you need to (bold, list, etc.) rather than formatting as a heading/subheading.
#<span style="color:#FF0000;">H6 has no way to render on the Observatory at all. Don’t use</span>.
#<span style="color:#FF0000;">H7 is what MediaWiki calls “Preformatted” for coding purposes. Don’t use</span>.
#H8 is MediaWiki’s default way to style block quotes (we use “blockquote” [adj.] and “block quote” [n.]; note that they add a space per the noun styling, calling it “Block quote” in the dropdown Header menu selection on top of text fields). This renders as a body paragraph that is indented on both the left and right sides.
#*Use: This is for quotations that are at least three lines long that should appear in their own separate paragraph(s).
#*Does not appear in the TOC.
 
====== Double-check links in Article Drafts======
Always test your links and fix any broken ones before finalizing any page Draft. Ask your editor for help if needed. ''(See: [[Project:Observatory Users Manual#Links|“Links” in the Glossary]].)''
 
One common issue with links is if you accidentally used internal links instead of external links (easy to do, especially if you copy-pasted without converting to wikitext first). If when you click a link in an Article Draft, the result is a prompt to create a new page on the Observatory or an error message, that usually means it was accidentally formatted as an internal instead of an external link. Pay attention to if you used the single bracket <span style="color:#e83e8c;">[</span> (for external links; which you use for most links) versus double bracket <span style="color:#e83e8c;">[[</span> (internal links, only for pages on the Observatory or Wikipedia and its project sites) in “Source edit” mode, or click the link in “Visual edit” mode and see if it’s toggled to the wrong kind of link (internal when it should be external) and then change it to external and fix the URL to the desired result (you will probably have to remove '''<nowiki>https://observatory.wiki/</nowiki>''' and add in '''<nowiki>https://www</nowiki>.''' depending on what the original link was; make sure you copy from the URL bar for the correct page, since that’s easier than removing and replacing part of a URL—and '''always test the result again after you’ve clicked to Save that new link'''.
 
Note: This also applies to any text field in any namespace, not just Article pages but also in Guide pages, Author pages, Source pages, Classic pages, Area pages, and more.
 
====== Footnotes, Citations, and Links ======
Here are the best practices for footnotes (whether notes or bibliographic citations) in your Article’s Google Document/Word Document. Once you convert the document into wikitext and upload it to the Observatory, these references will become endnotes. You can insert a footnote by using the “Cite” button (the open-quotation mark icon) in the top ribbon of the Edit text field.
 
In your Google Doc or word processor file, use internal links to sources the same way you would with syndicated Articles if you do not want them to appear as endnotes/footnotes/references.
 
However, we usually want as much of the research you did to appear as references/footnotes at the end of the Observatory Article, so it’s recommended to both use internal links over text to cite sources available online and also to format your links as MLA-style endnotes/footnotes inside the Google Doc/Word Doc prior to conversion. Check the [[Project:Style Guide#Links and Footnotes|Observatory Style Guide]] for more information about citations.
 
In Google Docs:
 
#Put your mouse in the Article document where you want to insert your footnote, then click to keep your cursor there (it should remain blinking).
#In the top menu bar, click '''Insert''' and then pick '''Footnote'''. (You can also use the hotkey command+option+f on a Mac).
#A number will appear where your cursor was in the body text, and a line will appear at the bottom of the page where you can insert and edit your footnote text.
#Google Docs will automatically number your footnotes correctly if you have more than one.
 
The Pandoc/workflow conversion from .docx/.odt files into MediaWiki text files will automatically treat the endnotes/footnotes as references.
 
You may find it’s best to code these using the Visual Editor after upload for new Articles ''(see section: [[Project:Observatory Users Manual#Insert references via Visual Editing (recommended)|Insert references via Visual Editing (recommended)]] for instructions)''.