Getting Started
The goal isn’t to recommend one way of coding as being “the right way,” because there are so many different technologies, practices, styles, tools, frameworks, and libraries to use, and different people have different favorites. Instead, we break it down to the core, a single minimalist way that is predictable, transparent, and simple enough to not get in the way of learning what each demo is trying to teach.
The biggest advantage to adhering to these guidelines is that it will foster consistency across our samples and demos on Intel® DZ, which increases readability and comprehension overall.
What is a Code Sample?
Developers of all types have no hard and fast rules when it comes to defining code samples. They are looking to solve a problem and that usually involves code.
The many faces of “code” on Intel® DZ:
- Code Samples
- Code Snippets
- Projects
- Product Code Samples
- Code Examples
- Code Files
- Code Packages
In an effort to create a consistent feel for code across the community we will be simplifying down to 3 basic areas. Code Snippet, Code Sample, or a project/tutorial/how-to.
Code Snippet
Code Snippet – A small amount of code designed to illustrate a specific purpose. For example if you have a problem with your code and you’re asking for help. No one wants to see your whole application. They want you show them a Code Snippet which they can use to reproduce the problem. Code snippets are supporting characters to your story.
Code Snippets in an Article require:
- description of what the code is for (prior to seeing it)
- Copy/paste friendly code (no matter how small)
- Link to full documentation/additional resources
Code Sample
Code Sample – Much like a code snippet, samples follow the same guidelines. Just enough to illustrate a topic or problem. The main difference is a code sample is the lead story. It drives the purpose of your content from start to finish.
"Simple" Code Samples Requires:
- Clear Header
- Version #
- Intro
- Assumptions, Software and Hardware Requirements
- Skill Level
- Alternative options for easier/harder
- Copy/Paste friendly code (no images!)
- Clearly labeled headers for easy scanning
- End with a CTA (something else to do)
"Download Only" Code Samples Require:
- Clear Header Version #
- Assumptions, Software and Hardware Requirements
- Skill Level
- Alternative options for easier/harder
- Details about download
- End with a CTA (something else to do)
Complex Code Samples Require:
A linear content type that may have code samples, code snippets or just procedural items. Tutorials have a purpose or problem to solve and go through that solution one item at a time. They should be written in a very straight forward, plain english, and easy to translate way.
- Clear Header
- Version #
- in-page navigation
- Sample Details:
- Assumptions, Software and Hardware Requirements
- Skill Level
- Tested on
- Alternative options for easier/harder
- License
- Intro
- Copy/Paste friendly code (no images!)
- Clearly labeled headers for easy scanning
- Use images/videos for visual/onscreen steps (vs. trying to just describe it)
- Use headers, subheaders, bullets, etc. instead of one wall of copy
- Include troubleshooting tips (don't make developers hunt for them)
- End with a CTA (something else to do)
Writing Better Code Samples
When was the last time you sat down and on paper wrote out exactly how you would approach a code sample? It’s easy to jump in thinking you know exactly how it should be structured, only to realize halfway through that you need to go back and rewrite.
Here are some tips to getting better results and increase the popularity of your code sample.
The Best Topics are Specific
Samples and Tutorials that are popular and easy to follow are ones that are specific rather than overly general. Don’t offer the kitchen sink. Rather, focus on a single aspect of the subject at hand, which will be much easier to present in an effective way and will, as a bonus, be much more likely to gain SEO value.
Write for EVERY Audience
Always remember, we are not the developer. Keep a vision of the person you are writing for in your head and ask these questions…
- Do they understand all the concepts you’ve used in your tutorial?
- If not, explain them or link to another tutorial that does.
- Explain things conceptually, so the reader has a big picture of what he’s going to do. Then lay out instructions on how to use it step-by-step.
- How much time would they have to make sense of it?
- Use short, simple, declarative sentences and commands rather than compound sentences. It’s easier for the reader to digest one instruction at a time.
- Give directions in no uncertain terms
- Are some of your users beginners?
- Don’t Say Things Like “It’s Easy” or “It’s Very Good”. If something is “easy” or “very good” your readers will decide based on the evidence you present. Not everyone is at the same level. If you’re writing an article about the command line, and you say stuff like “It’s easy, simply type git [whatever]”, you’re going to alienate many readers.
- Whenever you use a technical term for the first time, define it. Have someone else check that you defined all new terms. There are probably one or two that you missed.
- When forced to choose between technically simple and technically efficient, choose the former
Test what reading comprehension level your code sample is written at online. Your audience (no matter who) will appreciate that the language is simple and direct. Their main goal is to learn about your code, not be impressed with your vocabulary.
Assumptions, Prerequisites, and Requirements
Don’t make your users angry by not letting them know what they need, tell them up front.
- Hardware list
- Software/Plugin/API list
- Programing Language Requirements
- Specific Computer Setups
Provide links to these resources, so they don’t have to go hunting on google.
Add tips like “If you have no prior experience, you will find a very steep learning curve diving straight into _____”. It will save beginners from frustration and give you the opportunity to get them to the right content quickly.
In the case of API/SDK samples, if you are using multiple APIs together point out what APIs are included, and what features come from where.
Include a Brief But Effective Introduction
Too many authors write intros that basically amount to “filler” content. Here’s an example of a bad introduction:
Front-end developers have been trying many different frameworks in recent years. Bootstrap is a really popular framework, and it has many tools you can use today. We no longer need to scratch our heads wondering how to create a cross-browser drop-down menu, or a responsive grid, or a tab switcher. Bootstrap can do it all. But how accessible are its components? In this post, I’ll show you how to take Bootstrap to the next level by making your Bootstrap website more accessible.
Notice all the unnecessary fluff leading up to the main point of the article about accessibility? Instead, the following is better:
Bootstrap is the most widely-used framework in the world. But a common complaint I hear is that its markup is unsemantic and inaccessible. Let’s use two Bootstrap components as examples to see if we can remedy this.
This intro is clear, it presents exactly the problem you’re going to solve, and it gets right into the meat of the post, which is how to make a Bootstrap website (or component) accessible.
In brief, a good intro has two necessary ingredients:
- Present a problem to solve
- Tell us briefly how you will solve that problem
Headings Alone Should Develop the Theme
A reader should be able to read the title of your sample, then read each of the primary headings in order, and get a good higher-level understanding of the subject being discussed.
To do this, your headings should be clear in stating which part of the article is now being developed and they should not be general or vague (Step 1).
Solve a problem with your example
Most examples don’t do anything useful. Instead, try to create code that solves a real problem. Writing “hello world” code teaches people to write code, but not how to solve issues with it.
Good code examples should answer the “how does this technology help me solve a problem?” and not the “how do I use this?” question. Code examples should get people excited about using the product and entice them to dive into the documentation to find out about the details.
Write Tool/Technology Names in the Correct Format
Do the necessary research. Take five seconds to look at our Intel TM List and the Third-Party TM List.
By writing tool names properly, in the way the creators intended, we show respect for these tools, adhere to legal requirements and we help to represent their brands correctly in our writing.
Code Tips
Have Consistent and Easy-to-Read Code Blocks
When including code blocks in articles and tutorials, there are a few general rules:
- Include working code that users can copy and paste
- Users will put it into production. Make sure it works, but does not do anything that will cause an app to be insecure, grossly inefficient, or bloated.
- Understood as quickly as possible
- Consistent throughout your example
- Descriptive
- Explain your code before you show the example
- Write smart code that explains itself, instead of “empty” code with comments throughout it
No Walls of Code
If any code block is longer than 10 or 15 lines, it becomes much harder for the developer to digest each step. You can try one of the following:
- Remove any unnecessary parts of the code.
- If you’re talking about one specific feature, don’t include all the elements that are not being affected with that feature.
- Split up the code and describe what’s happening step by step.
- Make it downloadable.
Show a working example
There is nothing more powerful than a way to see what the sample does by clicking a link or entering some data and sending off a form. You telling the readers that it works is one thing – the readers being able to try it out and seeing it for themselves is much more rewarding. For examples that aren’t easy to show online, video is a great tool of showing implementation and success.
Remember, users don’t care about code, but about getting projects done.
Link to the Latest Version of Your Documentation
If you are talking about, for example, Flexbox, you might search for the spec and find a link like this:
http://www.w3.org/TR/2014/WD-css-flexbox-1-20140325/
But that’s a static version of the spec that won’t change. What you want is the permanent link to the current version of the spec. So make sure the URL looks more like this:
http://dev.w3.org/csswg/css-flexbox/
Before you Publish - Checklist
We know you want to get this task completed, but before you hit that “publish” button, please take the time to go through this checklist to ensure your content has everything it needs to be a success.
Has someone, who was not involved in creating the content, tried to follow your instructions?
This alone will discover a number of issues with your sample and whether the directions are clear. If you can’t enlist support, here is a list of items to help QA:
- Have you listed all the requirements/assumptions/resources needed?
- Do you have all the steps?
- Are the steps in the right order?
- Is the code easy to copy/paste?
- Has the code been tested on multiple system setups?
- Do all of your links work? (don’t assume)
- Did you use the product names correctly?
- Do you have any large paragraph blocks? (Avoid walls of copy and walls of code)
- Have you checked reading level? (there are lots of online tools that can help ensure we aren’t over thinking our samples)
- Have you checked for legal compliance?