Digital Corps Reference Guides Style Guide

Helpful Staff for this Topic

Quick Tip!

Review the Digital Corps Voice Reference Guide before writing your Reference Guide to make sure you’re writing with the Corps voice in your articles.

Reference Guides assist students and staff at the Digital Corps with a variety of topics that may not be included in training, but are important to understand and learn. Topics include Best Practices, Content Creation, and Office Life, but all content should follow a specific format. This format encompasses writing style, content development, and how to use the WordPress content editor. This Style Guide covers a variety of topics to help writers maintain consistency with their content.

How To:

Write in an expository writing style
Write in a third-person point-of-view
Avoid passive voice
Add Quick Tips element(s)
Add the Staff Help element
Place and center images
Embed PDFs into an article
Add Templates into an article
Add H1, H2, H3 and H4 titles
Add code blocks
Write for a series
Format articles with lists, hyperlinks, and captions
Add tags and categories
Submit the article for review

Style and Tone for Reference Guide Articles

Expository Writing

Reference Guide articles use expository writing and are designed to help Digital Corps employees with a variety of tasks related to work conducted in the office. Examples of expository writing style are “how to” articles, business writing, and even text books. This means that Reference Guide articles should maintain a level of professionalism, while still providing some entertainment for the reader. Typically, Reference Guide articles will be technical step-by-step guides, rather than philosophical commentary.

Third Person Point of View

To maintain a level of professionalism in the articles, write content from the third-person perspective – where all actions related to the subject’s work are referred to with pronouns like, “he”, “she”, or “they.” Avoid using “I” and “we” in your writing.

Active Voice vs Passive Voice

Write Reference Guide articles in an active voice. Passive voice is generally a weaker form of writing since it is unclear who or what is making the action. Normally, you can spot passive voice by testing to see if the direct object of the sentence comes before the subject of the sentence. Incorporate the subject into your sentence before the direct object to write in an active voice. Words that end in “ing” are another possible indicator of passive voice. This also creates more concise and direct sentences with fewer words.

Passive: Designing the website was done by Riley.

Active: Riley designed the website.

Organizing Content

Web content is different than content written for a textbook or magazine article. Web writers must take full advantage of digital content writing resources to properly organize information. Writers should use proper header tags, incorporate visuals into the content, and engage readers with related content and hyperlinks throughout the article. Reference Guides follow a pattern of organization that takes advantage of custom and WordPress content elements. For consistency, use the following organization for Reference Guide articles (additional sections are acceptable and often needed).

Quick Tips
Staff Help
Introduction
Explanation
Conclusion
Related Articles

A Note on Writing 101/Entry Level Articles

Much of the content in the Digital Corps Reference Guides databank is written specifically for someone who expresses a higher level of understanding in a subject area. For example, a web designer may review an article in Reference Guides to become more efficient at writing HTML, CSS, or JavaScript.

However, many Reference Guides articles are written with a different audience in mind. Some articles may be written to prepare Junior Project Managers, team members, or other collaborators to better understand a specific aspect of a project. In this case, consider asking the following questions when writing “101 Articles”

Who is most likely to read this article?
What is the most important information that they need to understand?
How would a JPM use this article to their advantage?
Does a JPM or someone who is not directly involved with the creation of the subject in question need to know every detail?
How can I make this article easily consumable?
What distinction needs to be made to separate a basic level of understand versus an expert level of understand with the subject in question.

Add Quick Tips to Your Article

Quick Tips clearly articulate the most important takeaway from the entire article. Writers may incorporate Quick Tips throughout the entire article but one must always appear at the beginning, after the title and before the Staff Help section.

Article writers should try and limit the Quick Tips to a couple of sentences. The video below illustrates how to add Quick Tips to an article.

Add the Staff Help Element to Your Article

Reference Guide articles are written to explain a specific topic. Sometimes, the reader may need additional guidance. To point readers in the right direction, add the Staff Help element after the Quick Tip. Reminder: the Quick Tip is the first item and the Staff Help is the second item in the article layout.

The video below illustrates how to add staff members to an article.

How to Place and Center Images

Images and graphics can enhance the article and provide additional context for the reader. Article writers should try to incorporate examples of the article subject using images and graphics to help clarify parts of the article. These items can also break up lengthy blocks of text and make the article easier to read.

After an image is added to the article, it must be centered. This ensures that styling does not break the article.

The video below illustrates how to add images to an article.

How to Embed PDFs into an Article

Depending on the subject, a PDF document may enhance the content of the article. Embedding the PDF directly into the article ensures that the reader can easily access the content.

Before the embedded PDF is added, writers should save the PDF file to the WordPress Media Library. This ensures that access to the PDF is not lost even if it is removed by the third-party source.

The video below illustrates how to properly embed a PDF document in an article.

How to Insert PDF Files as a Download

Alternatively, a PDF file can be added into a page using the “File” block. This element allows writers to incorporate PDF files into the article without taking up as much space as a PDF embed. Files may be uploaded directly from computer files or from the Media Library.

When uploading files directly from a computer, the file will be saved in the Reference Guides Media library for future use. Remember to clarify if the file should open in a new tab with the sidebar under the “Block” tab.

The video below illustrates how to properly insert a PDF document as a file for download.

Add Templates to an Article

Templates are a great way to reference specific examples of best practices a the Digital Corps. If the article mentions a template for a User Experience Testing Plan, add a link to the testing plan with the Template element.

Generally, templates should remain within the Digital Corps content ecosystem and not lead to unknown or external websites.

The video below illustrates how to add the Templates element to an article.

Using H1, H2, H3, and H4 Titles

It is imperative to use headers rather than just bolding words of a paragraph to designate a title. To create a header, select the “Heading” element after you add a new block. The dropdown menu in the “Heading” block will allow you to specify between H1, H2, H3, and H4.

The importance of headings are displayed in descending order. Consider H1 as a main header, while an H2, H3 and H4 will designate sub-headers. Use the headers in order – for example, you would not have an H1 header followed by an H3 header.

How to Add Code Blocks to an Article

Some articles may require examples of code. To add code blocks for HTML, React, and other markup/languages, use the Code Block element. Below is an example of a JavaScript code block.

$(document).ready(function(){
	$('nav').on('click','a',function(e){
		e.preventDefault();
		var section = $(this).attr('href');
		console.log($(this).attr('href'));
		var scrollPosition = $(section).position().top - 80; //80px additional for the menu height
		console.log(scrollPosition);
		$('html, body').animate({
			scrollTop:scrollPosition
		},500);
		return false;
	});
});

To add a Code Block, click the “plus” icon and select/search for “Code” in the list of items. Select the appropriate language from the menu on the right side of the screen.

How to Write for a Series

Many Reference Guide articles may be a part of a longer series – meaning that part one should logically come before part two. For example, before coding the CSS of a website, the web designer must first code the HTML. This series would be organized in the following way.

How to Write HTML
How to Write CSS
How to Write JavaScript

To designate an article as a part of a series, refer to the sidebar menu on the right side of the editor, under the “Document” tab. Under, “Series” the writer may either select from an existing series, or create a new one.

Ordering the Articles in a Series

Sometimes, writers may need to re-order the posts in a series. Reference Guides has a built-in panel to format the order of a series, as well as it’s series title and description. The video below illustrates how to change the order of articles in a series.

General Article Formatting Recommendations

The built-in WordPress elements add new layers of formatting and functionality for articles. Additionally, the use of bulleted/numbered lists, hyperlinks, and image captions will enhance the content you write.

Bulleted and numbered lists are a great way to break up content. For long articles, writers may choose to incorporate these lists to create an index or focal point. Additionally, bulleted lists are helpful to provide examples that would otherwise take up unnecessary space if written as a paragraph.

Hyperlinks can reference other articles in the Digital Corps Reference Guide repository, external websites, or content sections in the article. To add hyperlinks, highlight a word and click on the chain icon that appears above the element block. Writers should elect to open external links in a new tab so the user does not accidentally lose access to the article they are currently reading. Refrain from using “click here” as the reference points for hyperlinks. Instead, add the link to relevant text in the sentence.

Image captions add context to a visual piece of content. They are also best practice for accessibility standards. To add a caption, simply click on the image block and the prompt to “Write caption…” will appear. Click on this prompt and write the caption. Captions should maintain the same expository writing format and active voice style as the rest of the article, while clearly (and concisely) explaining what the image is. Keep captions to one or two sentences.

How to Add Categories and Tags to an Article

Categories and tags help organize content on the Reference Guides website. This enables users to properly search for and locate content using menus. Categories and Tags can be added or changed in the “Document” tab in the sidebar menu on the write side of the editor.

Before publishing, writers must filter their content using categories and tags.

The Review Process

The review process for Reference Guides can seem confusing, but it’s important to ensure that the content meets all the necessary requirements.

Save the article as a draft.
In Slack, type “/review” into the #reference-guides channel.
Add the title. This should be the same as the Reference Guide title in WordPress.
Choose the reviewer. Depending on where the article is in the review process, please use the following review order.
1. Junior Project Manager(s) > Project Manager > Appropriate Team Lead > Brandon
Copy the WordPress public preview link by checking the “Enable public preview” box under “Status & availability” in the Document tab of the right sidebar.
Paste the public preview link in the appropriate place in the Slash Reviews window.
Include any necessary notes for the reviewer.
Submit and wait for any feedback.

After receiving feedback, please send the article back to the individual who provided a critique. Feedback should be addressed within 24 hours of the review.

All articles should remain in Draft mode until the approval process is finished. Once the article is approved, the original writer is responsible for publishing the content to the site.

Insert the Review Process Block

The Review Process Block outlines the next steps in the review process for a specific type of project. When creating an article about a video-specific project, the article writer may choose to disclose who the employee should submit their work to in the review process. To add this block, follow the same process for other blocks and search “The Review Process.” Below, is an example of the Review Process Block.

Project Review Process

JPM(s)
PM
Team Lead
Brandon

Next Steps

For further questions regarding the format, style, and tone of a Reference Guide article, please refer to staff members for questions. Additionally, article writers should explore previously published articles to fully understand the best practices. With so many different writers, it’s easy to lose consistency among articles. However, by using this guide to maintain best practices, article writers should not have a problem confidently writing about a variety of subjects.

Please refer to the articles below as examples of articles that incorporate various WordPress elements.

Check out these templates:

Responsive Code: Web Platforms :
http://3.15.29.224/articles/responsive-code-web-platforms/
Production Tips Series: Pre-Production Tips :
http://3.15.29.224/articles/pre-production-101/