Publishing Guide
Publishing Code Stories
This guide will show you how to use the new WordPress platform to:
- Set up your author profile
- Submit drafts to the publication workflow
- Review code stories from other team members
- Submit revisions to previously published code stories
Looking for a guide to creating new code stories on the WordPress platform?
Looking for help with drafting a better code story?
New Blog
We’re now using open-source platform WordPress for authoring, reviewing and publishing blog posts. As a result, some important URLs have changed. Please update your bookmarks and links to Real Life Code you may have on social media, personal blogs, etc. accordingly:
- New frontend (public blog): /developerblog/
- New backend (editor): https://dxcodestories.westus.cloudapp.azure.com/reallifecode/wp-admin
Your user account is linked to your Microsoft email address, and your password can be reset at the editor login screen.
When you log in, there is a dashboard of important links:
Your User Profile
One added feature of the new system is user profiles. Please set up your user profile in order to improve your visibility and the blog’s SEO.
You can edit your user profile using the Profile quick link on the dashboard (shown above) or from the editor sidebar (Users→Your Profile)
You can set your:
- Display name/nickname
- Personal website or blog
- Social media accounts (whichever are relevant for you)
- Google+
- GitHub (coming soon)
- Slideshare
- Stackoverflow
- XML feed
- YouTube
- Biography (appears on posts you author)
- Password
- Profile picture (via Gravatar, you can set a unique one just for your work email address)
Submit Your Draft
In order to solicit editor, peer and LT reviews, you must submit your draft to the code stories workflow within WordPress. Begin by clicking the Submit to Workflow button in the Publish widget on the righthand sidebar (as seen above).
The following window will pop up. Make sure to submit your draft to the Code Stories workflow. It will be automatically sent for the initial technical editor review. You can set a priority level for the code story, as well as a due date for publication, to ensure that time-sensitive blog posts will be reviewed first. You can also leave comments about anything the reviewers should pay special attention to or take note of.
Reviews
The reviewing process will be done using a workflow plugin for WordPress that will ensure all steps are complete before publication. It will also keep everyone in the loop about where new code stories are in the process, by sending out emails as posts enter the next stage, as well as notifications on the Slack channel.
Each code story requires the following pieces of feedback before publication:
- Technical editor (initial review)
- Peer reviewer #1
- Peer reviewer #2
- LT reviewer #1
- LT reviewer #2
- Customer, Product Team or LCA (if applicable)
- Technical editor (final review)
Workflow
We are using the following workflow for the initial publication process:
Slack Notifications
Notifications about updates in the review process have been integrated into the Slack channel. You can set your Slack preferences to recieve alerts whenever one of your code stories has progressed in the review workflow.
In the Slack app, go to Preferences → Notifications → Highlight Words. Add your publication name from the blog as is. For instance, if your blog display name (listed on your user profile) is “Bob Smith” add that, not “Robert Smith.”
Reviewing a Code Story
On the lefthand sidebar of the WordPress editor, click the Workflows button. When there are code stories awaiting review, there will be a number label on the button.
You will then be taken to your workflow inbox. Your inbox will show available code stories, as well as their priority levels and due dates so you can review the most urgent ones first.
You can review by hovering over a code story in the inbox and clicking View or Edit. You should only make minor edits (i.e. to spelling/grammar errors) without consulting the author(s). Any edits you make will be visible to the author in a compare/diff view.
You will then be taken to the regular editor where you can add feedback in several ways including inline annotations, which are contextual comments, (first two buttons below are to add and remove annotations), and longer editorial comments (fourth button) that show up in the workflow history.
Inline annotations highlight the text in question and show when you hover over it. You should use them for questions/comments about specific parts of the text. Here is a screenshot of what they look like in the editor:
When you mouseover an inline annotation, the comment will pop up:
Editorial comments show up in the sidebar along with other workflow history. You should use them for general statements about the code story, like overarching changes that need to be made. They will appear with the text you highlighted when you clicked the comment button:
Make sure to sign off on your reviews using the Advance Workflow button on the sidebar!
Technical Editor Initial Review
The technical editor will review your code story for content, formatting, and spelling/grammar before approving it for peer reviews. This step will help ensure that peer and LT reviewers can focus more on technical details and less on proofreading.
Peer Reviews
After the technical editor has approved your initial draft, it will be moved to the peer review process. Two peer reviews are required for each code story
The Slack bot will mention new code stories as they change status. You should also reach out to potential peer reviewers via the Slack channel, especially if you have certain people in mind. Your reviewers should include the following:
- A domain expert in the topic of your code story
- An engineer who is not familiar with the topic
Peer reviewers should review blog posts for correctness and completeness. Consider whether the author is telling a cohesive story about the project. In addition, make note of whether the author effectively guides the reader through the narrative and code. Would someone who is unfamiliar with the technologies described in the post be able to follow it? Are the explanations of the technologies and products involved accurate and adequate for a developer who is not an SME? Verify that the author highlights known or expected shortcomings, tradeoffs or caveats. Additionally, make sure the author explains opportunities for reuse of the code or expanding upon it.
Authors should incorporate peer feedback in a timely manner. If you do not agree with requested changes, please discuss why on Slack. Afterward, the technical editor can take a look at any major changes before the post is moved on to LT reviews.
Make sure to sign off on your reviews!
LT Reviews
The Slack bot will mention when code stories have moved onto LT review, but again, reach out to reviewers if you have someone in mind. Two LT Reviews are required.
Please incorporate feedback from LT members or discuss why not on Slack.
Make sure to sign off on your reviews!
Additional Reviews
If your code story requires additional reviews from a Product Team, LCA, or customer, seek those out before publication. It is the author’s responsibility to obtain these approvals.
Final Editor Review
Before approving code stories for publication, the technical editor will do a final brief review. If changes are required, author fixes will be requested in the workflow.
Revising Published Code Stories
You can make revisions to already published code stories easily. Open the post in the WordPress editor, make your changes, then click Make Revision in the Publish widget.
Just like when submitting a new code story, this button will add your revision to the workflow inbox. Revisions will need to go through a much more minor workflow before the live site is updated:
A reviewer can then look at and sign off on your changes, which will then be shown on the live site.
Please note that when you submit a revision, it will show up in the workflow as “Copy of [Your Original Title]” and will show in Posts as a separate item from the original post. This is not a problem, and when your revisions are approved by the editor the changes will be merged into the original post and the one with the title “Copy” will disappear!
Light
Dark