Editing Project:Observatory Users Manual (section)

===== 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)''.