Migrating Articles

The first stage of adding content to HelpHub is migrating the most popular articles from the Codex into HelpHub. These articles have been identified by page views and we have put together a list of the top 139 articles that contain user-focused documentation. We are tracking all of those articles on this spreadsheet.

As of 9/Jan/2017, all contents were migrated and being re-written.

Re-writing Articles Re-writing Articles

The Codex is a complex setup made after years of multiple contributions from many, many authors. As such, it is not necessary that the article that you are migrating or have migrated may be appropriate for end-users to understand.

In this case, we encourage the contributor to re-write the article afterwards.
Re-writing can happen on the staging site or at the production area of WordPress.org (exact subdomain to be determined)

The steps are as followings:

If you are familiar with Trello system:

  1. Get access right from @kenshino
  2. Open https://trello.com/b/18vfyppv/helphub-content
  3. Pick up one card from “Re-write Articles (Not Yet Assigned)” list

– or –

  1. Open this spreadsheet, refer “Re-written” column (Column ‘G’). Blank cell is not yet re-written article.
    • If “Assigned Editor” column (Column ‘D’) is blank, please type your name in it to reserve the article, and type ‘ongoing’ in “Re-written” column.
    • If “Assigned Editor” column is not blank, but you want to help the work, contact to the assigned person.
  2. If you think you need screenshot update, Type ‘Y’ in “Require More Screenshots” column (Column ‘F’). If not, Type ‘N’.
  3. Re-write articles.
    • The article should have been fully migrated
    • Appropriate edits must have also been made such as putting in [code] shortcodes and screenshots
    • Remove missing link, out-of-date plugin or theme information
    • Remove old sections such as WordPress V2.x
    • You may leave link to original Codex article. It should be replaced immediately before the release because the path structure is subject to change.
    • If possible, take a new screenshot. If it is difficult, please add some comment (For example, ‘We should replace the 2nd and 3rd images by the latest one’).
  4. After completion, Type ‘Y’ at “Re-written” column

Please ping @Kenshino or @atachibana on Slack if you need an article reviewed or help.

Top ↑

Release Release

It is our belief that re-writing the articles is a long term effort and it is not blocker towards releasing version 1 of HelpHub. Therefore it is necessary for the migration to be done in its entirety whether or not re-writing will be done immediately after migration.

Top ↑

How to migrate content How to migrate content

Note: Thank you for your help. Phase 1 migration was completed.

The spreadsheet with the articles flagged for the initial run of content migration is open for anyone to edit. It contains a list of Codex articles (names & URLs) as well as info on who is working on each article, and what the status of the article migration is. If you would like to assist with migrating articles, these are the steps you need to follow:

  1. Request access to wphelphub.com by sending your email address to @Kenshino or @justingreerbbi on Slack.
  2. Pick an article that you would like to migrate and add your Slack username to the ‘Assigned’ column in the spreadsheet.
  3. Create a new post on HelpHub and copy the content from the Codex article into it
  4. Edit the content, paying particular attention to the following:
    • Use simple language – understanding is key!
    • Use semantic headings: No H1s in the article content – start sections with H2s and work down from there where appropriate.
  5. Add screenshots where appropriate – if the article is describing any user interface element then it must include a screenshot.
    • Animated screenshots can sometimes be appropriate – in those cases, please use your discretion and bear in mind that a user must be able to stop an animation that lasts longer than 3 seconds and animations must never autoplay.
    • Images should be uploaded at full screen size. The optimal image size is 1280 x 1024. When uploading to the Media Library choose the thumbnail size large for the image to fill the width of the content area.
    • To take screenshots that look great, resize your browser window. By resizing down, you can take screenshots of the specific areas of the screen that you are referring to. Smaller images should be aligned right.
    • Use either .png or .jpg files.
    • All images should have a descriptive alt tag for accessibility. You can view the WordPress accessibility standard here.
  6. If there are code elements or code examples, please use the [php] shortcode. For examples, see this page for all options to make your code examples more readable and aesthetically pleasing.
  7. Once you are happy with the content add a ‘Y’ in the ‘Migrated’ column and add the URL for the article on HelpHub into the ‘HelpHub URL’ column.
  8. Jump into the #docs channel on Slack and ask for some feedback (if you type the word ‘HelpHub’ then some of the key stakeholders will get pinged directly) – once everyone is happy then add a ‘Y’ in the ‘Complete’ column for the article.

For now we are focusing on those 139 articles. Once they are complete we will expand that to start migrating more articles across as well as writing new content.

If an article is marked as having being migrated, but is not complete, then you can also work on that directly inside HelpHub.