Writing Guide

Below is the guide for authoring new posts in WordPress, followed by a help section on writing and editing better code stories.

If you are looking for info on the review and publication process, please check out the Publishing Guide!

Writing in WordPress

Creating a New Post

To create a new post, click Posts from the dashboard then Add New, or alternatively from the sidebar (Posts→Add New).

Post Title and Permalink

When you add a title to a new post, it will automatically be converted to the slug for the post’s permalink (that is, its published URL).

You can edit the permalink, however, you should only do so before publication. After publication, you can change the title as needed without altering the permalink; doing so will prevent broken URLs and poor SEO.

Featured Image

Make sure to set a featured image for every post using the widget on the right-hand sidebar:

A featured image should convey what your code story is about. Some possible ideas are: screenshots of your code in action, a diagram of how your concept works, photos with an appropriate license that illustrate your code story’s point (for example, a robot for a story about chat bots), etc.

You can also create your own header image using Microsoft resources from aka.ms/brandcentral

Excerpt

Writing a custom excerpt for every blog post is important for SEO as well as catching blog readers’ interest. An excerpt should be approximately 1-3 brief sentences that describe your project’s problem and outcome. It should also note the main technolog(ies) used in your solution.

To edit the excerpt, open the Screen Options toolbar in the top right corner of the editor. Under Boxes, check Excerpt.

Now your visual editor will have an Excerpt widget in the righthand sidebar.

Categories

The Categories widget is located in the righthand sidebar of the visual editor. Check the appropriate categor(ies) that your post falls under.

Please do not add new categories without first clearing it with the Slack channel.

Tags

The Tags widget is located in the righthand sidebar of the visual editor. Type in multiple tags to describe the content of your post, or select from a list of the most commonly used tags on the blog.

When typing in tags, the system will suggest existing tags that contain your text. It’s likely that most tags you will you are already in the system in some form. For instance, if you wanted to use the tag “Event Hubs” and typed it in, you should select the equivalent suggestion “Azure Event Hubs.” Doing so will help users find related posts on the blog more easily.

WordPress Visual Editor

You can choose to write in either the Visual or Text Editor in WordPress. The Visual Editor is a WYSIWYG editor, and the Text Editor is a bare-bones HTML editor.

Each option has its own toolbar (Visual with buttons to generate formatting on the backend, Text to add formatting code directly). You can toggle back and forth between them, as well as switch to full-screen editing mode at any time.

You will likely wish to use the Visual Editor so that you can see how your post will look as you go. (Previewing the full post in the context of the blog will be covered in a later section.) The Visual Editor Toolbar is very extensive and will cover most writing and formatting needs.

Hover over the toolbar buttons to see the equivalent keyboard shortcuts. Basic keyboard shortcuts such as Ctrl+Z for Undo, Ctrl+B for Bold, etc. will work.

You can toggle the extended toolbar using the Toolbar Toggle button (Shift+Alt+Z) for extra options.

Adding Media

Adding image and audio files to WordPress is as easy as drag-and-drop. (You can also use the Add Media button at the top of the editor.)

After dragging and dropping your media into the visual editor, the Media Library will pop up and show the attachment details for the file you have just uploaded.

It is important to fill out Alt Text for every image you upload. The other fields are optional, although useful in some cases (in particular, Caption). Alt text is critical because it:

1. Allows visitors who use screen readers to understand the content of the image
2. Helps people find your content because search engines will index this text
3. Provides context if your image cannot load properly

Don’t Forget Alt Text!

Alt text should describe the gist of what your image represents. For instance, in the example above, some appropriate alt text might be, “object detection tool identifying cats in a photo with bounding boxes.” If you only said “cats” it would not adequately describe the point of the photo (object detection). If you only used “object detection” it would not be illustrative enough (what is being detected? how is it being detected?).

You are also able to select the size and alignment of the media before inserting it into the post. You can also set the image to link to a custom URL or the media file itself (useful if you are inserting a large image at a smaller size).

Please note: there is a 64MB upload limit to cover large files that need to be attached, but any inline content must be a reasonable size to keep page load time low.

Adding Code

You can add syntax highlighted code to your posts with the code button located in the visual editor toolbar:

A prompt will then appear to set the language, content, appearance, etc. of your code:

You can of course also add code snippets, GitHub Gists, etc. manually in the text editor.

 

Please note:

• Copy/pasting text from VSCode into the editor can cause random line breaks
• If HTML brackets will not render, use the alternatives &lt; (<) and &gt; (>)

Search Engine Optimization (SEO)

Search engine optimization is necessary both for establishing your reputation and making sure your code stories reach as wide an audience as possible.

Make sure to create a unique featured image for each blog post (this topic is covered further in the Publishing Guide). It is a great way to illustrate the content of your code story. Also, it will make for more eye-catching thumbnail images when your posts are shared on social media. Below are some ideas for creating a great header image:

• Screenshot your code in action doing something neat
• Use stock images (under free commercial license) that relate to the code’s purpose
• Create something from the resources in Brand Central
• Consider how the image looks scaled down on smaller monitors or tablets
• Choose something with color to grab people’s attention and highlight interesting elements of your code story

Write alt text for all images. Alt text is what appears in place of an image when it is unavailable or a user is reading the page with a screenreader. You can do this when you insert an inline image. It also makes for a better description for search engines to pick up on, leading more people to your code story.

Use <noscript> tags if you are using something like GitHub gists to display code. Search engines may not index all your content correctly otherwise. It also has the bonus of making the code accessible to people using a screen reader.

Sections

It is a good idea to use headings and sub-headings to divide your code story into sections. Headings make it easier for readers to understand your blog post, as well as find the information they are looking for more quickly.

Since the blog format puts the post’s title in Heading 1 format, it is advisable to start your section headers in the Heading 2 (Shift+Alt+2) format.

“Read More” Tag

Another way to divide your code story is by adding a “Read More” tag. This tag sets how much of a preview of your code story will show on the front page of the website. Adding it after your introduction or shortly thereafter gives readers a nice preview of your story that will make them want to click through and read it in its entirety!

You can add the tag with the button in the editor toolbar or Shift+Alt+T.

Previewing Your Post

It’s advisable to preview all posts “live” on the blog before submitting them to the review process.

In the Editor, simply click the Preview button in the Publish widget on the righthand sidebar.

Review Process

Once you have saved a draft of your new code story, you can then submit it to the review process for the technical editor, peer reviewers and LT reviewers to look at.

Please then follow the steps to submitting drafts to the review workflow in the Publishing Guide.

If you are looking for help with reviewing other team members’ code stories, please reference the reviews process section in the Publishing Guide.

---

Writing & Editing Help

Good writing starts with good architecture!

Even when writing is not your specialization, you can still easily develop a fantastic code story to show the value of your hard work.

Architecting a Code Story

Plotting out a code story beforehand takes only a few minutes, and can shave hours off the writing process. The outline below is very generic and by no means written in stone, but it could be used (or tweaked for use) in almost all code stories. It is formatted as a list of questions because it is often easier to answer a few little prompts than just come up with an introduction out of your head.

>Introduction

• What is the “what if?” question that sums up your project?
• What was the initial problem or goal that prompted this project?
• Who did you partner with on this project?
• What sort of solution did you come up with?
• What are the core technologies and languages used in your solution?

Catalyst

• What was the partner trying to accomplish?
• What issues did they run into if they tried to address it before talking to PCT?
• Why did they decide to turn to Microsoft and Microsoft technologies?

Planning

• What did you think the solution would initially involve?
• Which technologies did you want to incorporate?
• Why did you want to use certain technologies in your solution?
• What did you think you would need to develop yourself in this project?

Development

• How did you architect your solution?
• Under what limitations were you working?
• Did you have to build/incorporate hardware?
• Did you have to make the project cross-platform/platform-agnostic?
• What problems did you run into as you begin development?
• How did you fix or circumvent any problems?

Solution

• What did your final product turn out to be?
• What praise did the partner have for it? What praise did you have for it?
• What is the extensibility of the solution? Will it be reused in other projects for the partner, or on PCT?

Conclusion

• Where is the code going from here on out?
• How reusable will this code/solution be for other developers?
• Where can developers find the code?
• Can people contribute to the code? Can they fork it?
• Where can developers send their feedback and questions to the author?

Hopefully, by answering these prompts you can get inspiration for what to include in most code stories!

Soliciting Initial Feedback

To make sure that a code story idea is on target, you should first solicit feedback from peers. You can do so via the #case-study-talk Slack channel, email or discussions.

You can also seek out assistance from the technical editor at any time in the writing and publication process. You don’t even need a draft! Doing so will help ensure that your code story is cohesive and not missing any important sections or points, which allows peer and LT reviewers to focus on technical issues rather than writing-related ones. One technical editor review is required before moving onto the 2 peer and 2 LT reviews.

Clarity

It is important that an audience of developers worldwide can understand all code stories. You can take a few steps to ensure that your writing is sharp and comprehensible. If you are not sure whether something you wrote is clear enough, read it out loud. Sure, it might feel silly. However, it’s also the closest you can get to reading your code story as a reader would. It helps you catch missing words, and realize where there are run-on sentences and many other problems.

Another way to make a document easier for readers to follow is by varying sentence length. Below are two versions of a short paragraph:

Version 1: We partnered with Guide Dogs on this project. We used Microsoft Azure to create this service. We made the code available on GitHub.

Version 2: On this project, we partnered with Guide Dogs. We created this service using Microsoft Azure and made significant use of Event Hubs. The code is now available on GitHub. Please check it out!

The first version uses sentences with an identical syntax and similar lengths. It is technically correct but likely to make a reader lose interest. The second version varies the structure of each sentence and a number of words. It makes the sentences sound distinct and livens the paragraph up, which keeps a reader’s attention better. Variety is the spice of life!

When you are reading through a new code story you have drafted, it is also useful to keep your eyes peeled for a few terms that often signal a pesky problem: this/these and which and it. The issue is that these words are supposed to precede a noun in most cases. In practice, we often drop the noun when speaking and writing. For example:

1. You can use machine learning to determine intent. This is how we solved the problem.
2. Copy the key out of the API and use it.

In the above examples, the bolded words could refer to either one of the italicized items or even both. It is not impossible to figure out the meaning in context, but adding in another word or two could clear things up for your readers.

Also, these code stories are being published for developers around the world to read. If someone is utilizing automatic translation software to read the code story, making your writing more precise improves the translation potential and user experience.

Spelling and Grammar

Obviously, everyone in 2016 understands it is quick and easy to pass your work through a spelling and grammar checker like that in Microsoft Word. The editor will run code stories through Grammarly, as well, which also has a limited but free Chrome and Firefox extension that may be useful to you. One caveat is that it will make bad recommendations to change programmatic terms, capitalize words in code blocks, etc.

It is also worth looking at your and others’ code stories for issues such as:

• Consistency for words that have multiple accepted spellings. Whether you prefer to spell it ’email’ or ‘e-mail,’ pick one and stick with it throughout the document.
• Cases where you should use uppercase or lowercase. Your code may include a term like ‘cli’ but in a blog post, it is better to capitalize it as CLI to indicate it is an acronym.
• Product names. If you are unsure of the proper wording of product names, check out Microsoft Brand Central. If someone is using an incorrect or outdated product name, please point it out.