Content Authoring and Migration

Migration Note

Right now we are in the process of migrating content from the old site. It is important to keep in mind that while migrating content, you are expected to fix up any problems with it, and get it looking fresh and clean again. The old site is really quite a mess right now, and there are very few pages that can be transferred over as they are.

If you're not prepared to take the time to make sure the page you're transferring is all cleaned up, don't take on the task.

Also, be sure to read the Migrating Content section of this page.

Introduction

The purpose of this page is to give you basic instructions on how to add content to this website.

Keep in mind that we are using Markdown, not HTML for content. This should make things much easier in the long run, but it does take a little while to learn.

You are expected to read and understand this page, the style guide, and the Markdown guide, at the very minimum.

Things are still very new right now, and everything may not work as well as it should. If you notice problems, or things that seem harder than they should be, please tell someone. Now is the time to get things working well; don't be afraid to complain, or you'll be annoyed by the same problems for months to come if nobody else notices.

Authors can create and edit pages, but their changes must be reviewed and approved by moderators.

The first step is to log in to your account using the Administration > Website Login link in the menu on the left side of the screen.

If you do not yet have an account and want one, contact Joshua Simmons for now.

Once you have logged in, you will notice a black bar along the top of the page. The My Workbench link in the top left takes you to the easiest place to create content, view content you've created/edited, etc.

Click on the My Workbench link, this will be the starting point for many of the following instruction sets.

Creating Pages

Starting from My Workbench, click on the Create Content tab near the top, and then on Basic Page. A Basic Page is any page of just content, no matter how big and complicated, don't read too much into the name.

Note: there are actually several ways to reach the same point on the site currently, feel free to use one of the others if you prefer.

Once you're on the page where you can input a title and body text, skip down to the section on actually editing content.

Editing Pages

The easiest way to edit an existing page is to simply log in, and then navigate to the page you want to edit.

Near the top of the page will be a tab called "New Draft", click on that to start a new draft editing the page. Any changes you make will need to be approved by a moderator before they become part of the published version.

Actually Writing/Editing content

Once you are on the page to create/edit a page, the real fun begins. The "Title" in the title of the whole page, and appears verbatim at the top when the page is viewed. It is also used to generate the default URL that the page will be visible at, and the default menu text that will lead to the page. Keep those in mind, and choose a good title.

If you are editing a page, you should almost never need to change the title.

The main content of the page is of course in the "Body" section. Be sure that you read and understand the Markdown Guide and the Style Guide before continuing.

Adding most content is explained in one of those two documents, mainly the Markdown Guide. One thing that is worth mentioning here though, is how to upload and display images on a page:

Including Images

If you look below the "Body" section, you will see an "Upload Images" section, and a textbox labeled "Add a new file". That is of course used to upload files for use in the current page.

Click in the "Add a new file" textbox or the browse button and you'll be able to choose an image file from your hard drive. Then click the "Upload" button to actually upload it.

Now that the file is uploaded, you should see it in a big box right under the "Body". Be sure to set the alt and title text for the image, where appropriate. Try hard, those are important!

Once those are set up, you can actually go about inserting the image into its proper place in the page. This is done by placing the text cursor in the "Body" text at the right location, and clicking on the "Insert" button near the image that you want to insert.

It will automatically insert the correct tag to show the image at that location.

For advanced users, there are a few CSS classes that you can manually add to the inserted img tag. They are:

  • alignright: floats the image to the right
  • alignleft: floats the image to the left
  • graphic: use on images that are used as inline graphics of some sort, it removes the border

Here is an example:

<img src="http://example/example.png" class="alignright graphic"/>

Getting Your Content Published

The "Preview" button will allow you to see what you have already input, be sure to preview your changes and make sure you are satisfied before you submit them for moderator approval.

Once you are satisfied, fill in a revision log message, and click on the "Save" button at the bottom (actually you should save fairly often to avoid losing work, but definitely at the end).

The revision log should describe what you have done, and/or why. It will be visible to moderators, other authors, and various other site administrators.

Important: even after you have saved, your content is not visible to moderators, you must continue on.

Once you have finished a change and think that it is ready to be published, look at the top of the editing page. You should see a "Moderate" label, with a select box near it.

Note: not the "Moderate" tab.

If you do not see it, it probably means that you haven't yet saved.

In order for your content/changes to be sent to moderators for approval, you must select "Needs Review", and then click apply. That's basically it, your content will now be either approved (with or without edits), or sent back to you for more work.

Note: you can also request moderation of Drafts that you've already saved in the My Drafts tab of My Workspace, mentioned above.

Migrating Content from the Old Server

If you are migrating a specific page from the old server, follow this set of steps.

  1. Copy the entire content, as-is into a new page on the new server, and Save it. This will create a new draft that has the original content, and moderators/authors will be able to go back and see it later if they need to. Do not publish or request moderation in that state. You must convert it to Markdown, and more importantly, make sure that the content is up to date, follows the style guide, and looks good.
  2. Then edit the content however you need to, and continue as usual.

This will ensure that there is at least some record of the original page, in case you need to change and remove large sections.

You can either transfer the HTML of the page in the first step, or just the text, depending on the page. You will have to make a judgement call, based on how annoying the HTML will be to change and how much information is lost just copying the text.

One issue you may have is in migrating content that links to other content on our site. If the content you want to link to is not available yet, just use the old URL and we'll have to go through and fix it up later. You still need to change the links to the new Markdown format.

These links should be internal identifiers:.
good: /resources/blah.html
bad: http://usgo.org/resources/blah.html