HC Style Guide: Design, Code and Icons

Welcome to the Self Service Style Guide!

This is a living document full of tips and tricks to format the best articles on the planet. There are lots of other resources here as well, from coding to design and beyond. You are welcome to add or recommend tips and tricks that are helpful to you, either editing here or making a Help Center content change Jira ticket.  

Feel free to bookmark and visit this article via Zendesk in edit mode whenever you'd like, and click the </> icon to peek behind the curtain at the code that makes this article (and all others) a reality.

The concepts of awesomeness

• HTML resources
• Examples in Coding
• Help Center Design
• Picturesque Examples
• Grammar and Global English

HTML Resources
Coding help and hints

HTML can look like a lot all at once, but in many ways it's simpler than sentence structure and writing descriptions. If you get your commands wrong, the code will tell you right away (as opposed to waiting for feedback from your readers).

Here are some valuable links for learning to code:

• W3 Schools HTML Tutorial
• HTML Cheat Sheet
• Former teammate Travis's HTML and CSS Tutorial

All links should have the "Open in new tab" box checked. It's standard for the Help Center, and convenient for the reader. 

Another useful tool in your quest to organize code is the Sublime Text app, which you can download for free here. Copy and paste full articles or partial bits of code when the app is in HTML mode (see that handy yellow arrow in the lower right corner).  You'll be able to see the code in all it's glory, fully colorful, meaning easy viewing to spot errors.

Also, when copying and pasting code, use Command+Shift+V instead of just Command+V. This will prevent excess code that can mess up formatting to appear automatically.

 

---

Examples in Coding 
Lists, Notes, Tables, Anchor Points 

There are two types of lists we use for articles depending on what you need. The most common is an ordered list <ol>, which are organized by number: 

1. Numbered lists are really great for step by step instructions when things need to happen in a certain order. 
2. Oftentimes, they are followed by a screenshot. To insert a screenshot in articles without having a number next to the screenshot, use Shift+Enter. This will insert a break so you can add a screenshot.
3. Another way to do this is to insert the screenshot directly after the cursor with no break. Simply click the insert image button in Zendesk with no space, and the screenshot will format automatically. 
   
4. Hitting Enter alone will continue the numbered list that was started above.
5. Enter two times will automatically end the numbered list with a paragraph break.

The second kind of list is an unordered list or <ul>, denoted with bullet points:

• Great for listing a series of features
• Things that don't need to be in a specific order
• I love using bulleted lists to explain a series of buttons or options within a screen

You can interrupt a numbered list, like a step by step guide, by simply adding the code to an unordered list within the code. Here is an example:
<ol>
<li>Step 1...</li>

<ul>

<li>Point A</li>

<li>Point B</li>
</ul>
<li>Step 2...</li>
<li>Step 3...</li>
</ol>

Anchor Points are a way to organize your articles so that people can easily get the information they need without scrolling through the rest. To see how they work, check out the coding in this very article, beginning with the concepts of awesomeness above.

Check out the beautifully styled table below. You can copy the code for it behind the curtain, starting with <table class="DevTable"> and ending with </table>. This table includes our styled headers and a bolded first column, as well as alternating colored rows. 

Header Title 1	Header Title 2	Header Title 3
This is our table	Text cell 1,2	Text cell 1,3
The rows alternate	Text cell 2,2	Text cell 2,3
And the first column is bold
Copy and paste this table	for any article!

Note: Here's a note! Notes should be used sparingly, as they are a great tool to call out information that is important to users' experience within Showpad. Check out the </> button to see to formatting for this note. Borrow the code for your own note in a new article if you'd like!

---

Showpad design
Jan 9, 2020

The image size requirements for the icons you see pictured are 160x160 pixels. It's important to select icons that represent the feature you're writing about. You wouldn't want to goof up and post an Android robot when the feature is for an Apple iPad!

The purple and pink images we use for both What's New and What's Coming can be found in this Dropbox folder of Showpad icons. 

Another great place to find design information, colors, zoom backgrounds, and more is in the Showpad Brand Center. Use Okta to access all the employee resources available. There is a lot to explore - I recommend checking out Showpad colors and copy style. 

When using examples and screenshots in articles, the only place to safely procure content is in the Showpad Dummy Content dropbox. Always use our IT & Security approved test emails and names for testing and screenshots in the MyOrganization instance to avoid any privacy or legal complications. These include Test Admin ([e-mail]), Test Manager ([e-mail]), Test Buyer ([e-mail]), Test Learner ([e-mail]), and Test User ([e-mail]).

When in doubt, check with Cedric. 

---

Picturesque examples
Jan 9, 2020

Templates and examples can be handy for special projects as well as day-to-day life handling requests in the Help Center.  Here's a table of useful examples, templates and other helpful bookmarks:

Note: You will need to be logged onto the VPN to see the Confluence links (marked with a *). If you get a 404 error when you click them, try the VPN first!

Example with Link	Used for
All Articles Need an Update Sheet	Whenever there is a UI change, use this template instead of pulling the articles yourself. It is organized by section and all titles are links.
Documentation Tools Confluence*	Get access to all our staging and test instances with integrations and accounts for every need.
Self Service Google Drive	For projects, drafts that don't need to be seen outside of Support, and anything else
Template for Administrator Articles	This Zendesk link will give you a good start on code and formatting for admin articles
Template for User Articles	Another example in Zendesk to get you started writing user articles
Help Center Article Builder Confluence*	The structure and tips laid out for every type of article you'll encounter.
Coding Resources*	This page includes the HTML code for anchor points, slider images, and more.

---

Grammar and Global English
Jan 9, 2020

The Help Center is accessible all over the world, and for that reason, we need to make sure that it truly is accessible all over the world. This means that we choose to write with clear direction, avoiding idioms or local phrases that may be confusing in translation. It's also important that we are inclusive to those with different accessibility needs. With all that in mind, we should be good writers too!

To all of those ends, here are some resources that will help provide guidance. At the bottom of this page, you can also download Microsoft Office's official Style Guide pdf for further information.

Your Grammar and Global English helplines:

• Write the Docs presentation on accessibility
• Global English Guidelines presentation
• Microsoft Office Online Style Guide