This style guide includes details of the Smashing Voice and Tone, as a guide for anyone writing a Smashing article.
This style, voice and tone guide aims to share some of the things we think helps to make a great Smashing Magazine article.
Sharing practical examples are important. After reading the article, our readers should not only have gained new insights and ideas but also know how to actually implement these insights and ideas in practice. Also, we want you to share your expertise with us, mistakes you’ve made, things you’ve learned in your career and things you wish you had known earlier. The more practical your key points are, the better.
Also, don’t be afraid to express your own opinion . When sharing your statement, please make sure to provide a link to the sources that support your claims. Our ultimate goal is to engage the community in meaningful design discussions — not flaming ones. Last but not least, be concise, and don’t exaggerate; for example, “absolutely awesome!” and “the coolest feature I’ve ever seen!” doesn’t quite fit Smashing Magazine’s objective style.
Our audience consists of web professionals; you can assume a familiarity with general web design and development terminology and computer literacy. However, beginner articles on a specific subject are very useful, for people learning a new tool or technology.
If writing an article for an audience new to a tool or technology, outline in the introduction what the starting point is, and your intended audience. For example, an introduction to Vue.js aimed at people who are already experienced JavaScript developers would have a different starting point to one aimed at web designers with little prior JavaScript experience. Explaining that starting point will encourage your ideal reader.
When writing a more advanced piece about a tool or technology, mention in your introduction your assumed level of knowledge. You can also use that to point the reader to a good introduction to the subject that they should read before reading your article.
Titles are hard, and we can help you if you are stuck. When thinking about the title of your article, consider the following points.
Include relevant keywords in the title where possible.
67 characters will display in the Google search result, so either keep the title under this length or make sure those first 67 chars describe the article.
Quite often titles require the user to know what they are looking for to find the article. Think about the problem you are solving when writing your title. What is your ideal reader trying to do? What might they type into a Google search?
If you are struggling to title your piece, send us a few suggestions - even if they are rough ideas. Another set of eyes on the problem will often help.
Start your article with an introduction that explains to the reader why they should continue reading the article. People are busy and will often scan an introduction to see if this is something useful and relevant to them.
Think from the point of view of your reader, and answer these two questions:
A good way to close an article is to offer the reader some next steps. That might be a list of further resources or a single action point. If they have invested the time to read your article what would you like them to do now?
Images can help bring your article to life. These might include screenshots of the work in progress if writing a tutorial, or examples of websites that highlight a point you are making. As detailed in the article template these should include Captions and alt text, and remember to send us a zip of all images in your article along with your final draft.
Images should be at least 800 pixels wide, and if they are not owned by you, or screenshots, we need to know whether we have the right to publish them.
You can have code formatted inline in your article, or we can embed CodePens or similar. You might also consider linking to a GitHub repository including the worked application.
Smashing authors write in their own voice. We don’t edit our articles to fit a strong house style, however here are some guidelines.
Unless writing an advanced piece on a subject where you can reasonably assume the reader to know specific terms relating to the subject, explain any specific terms the first time you use them, and avoid unnecessary jargon.
Use the official terms of the things you are describing. For example when talking about CSS - how is that property described in the specification? This helps readers to search for more information.
When quoting someone directly, or using information that builds on the work of someone else in the community be sure to reference that person by name. In addition to ensuring people get credit for their work, this also helps your reader to go back to the source if they really want to explore the subject. It can often be helpful to quote someone directly and then add your thoughts building on that quote, as this then clearly shows the attribution.
Statements such as “30% of people thought that …” need a reference and a date. If not a link to an online source, details of where this information came from.
When referring to an individual or an organization, refer to the spelling and capitalization used by that entity.
Use title case throughout the article.
Use descriptive link text, rather than “click here to find out more.” The link text should describe the target of the link.
Ask your editor at Smashing - we’ll keep updating this style guide with any frequently asked questions or suggestions from authors.
Last updated 29th December 2017 by Iris Lješnjanin