how to write technical documentation

If you’re looking to add some styled notes, cautions, and warnings to your Zendesk, this post will help you out. I needed to create some styles for a documentation project and I’ll share the styles here. 

For my project, I decided to create coloured boxes that have icons, as shown below.

There are lots of different ways of achieving this, but I went for SVG icons that are added directly into the CSS. For the CSS, I copied some code at garden.zendesk.com and butchered it a little bit as I didn’t want the closable boxes. For the SVGs, I used 16x16 pixel svg icons that I converted into URI data by using dopiaza.org

Don’t worry, it’s not a huge, complicated process! This post looks long because I’ve included all of the CSS code you need to add. 

 

Here’s the CSS

Here’s the CSS I used: 

/* notes, warnings, etc. */

.c-callout{
position:relative;
border:1px solid;
border-radius:4px;
padding:20px 40px;
line-height:1.42857;
color:#333333;
font-size:14px;
margin-top:1.5em;
margin-bottom:1.5em;
}

.c-callout__title{
display:block;
margin:0;
color:#333333;
font-weight:600;
}

.c-callout__paragraph{
margin:10px 0 0;
}

 

.c-callout–info{
border-color:#047cf5;
background-color:#ffffff;
background-image:url(“data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0ZWQgYnkgSWNvTW9vbi5pbyAtLT4KPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4KPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij4KPHBhdGggZmlsbD0iIzAwMDAwMCIgZD0iTTcgNC43NWMwLTAuNDEyIDAuMzM4LTAuNzUgMC43NS0wLjc1aDAuNWMwLjQxMiAwIDAuNzUgMC4zMzggMC43NSAwLjc1djAuNWMwIDAuNDEyLTAuMzM4IDAuNzUtMC43NSAwLjc1aC0wLjVjLTAuNDEyIDAtMC43NS0wLjMzOC0wLjc1LTAuNzV2LTAuNXoiPjwvcGF0aD4KPHBhdGggZmlsbD0iIzAwMDAwMCIgZD0iTTEwIDEyaC00di0xaDF2LTNoLTF2LTFoM3Y0aDF6Ij48L3BhdGg+CjxwYXRoIGZpbGw9IiMwMDAwMDAiIGQ9Ik04IDBjLTQuNDE4IDAtOCAzLjU4Mi04IDhzMy41ODIgOCA4IDggOC0zLjU4MiA4LTgtMy41ODItOC04LTh6TTggMTQuNWMtMy41OSAwLTYuNS0yLjkxLTYuNS02LjVzMi45MS02LjUgNi41LTYuNSA2LjUgMi45MSA2LjUgNi41LTIuOTEgNi41LTYuNSA2LjV6Ij48L3BhdGg+Cjwvc3ZnPgo=”);
color:#333333;
}

 

.c-callout–tip{
border-color:#99ccff;
background-color:#e6f2ff;
background-image:url(“data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0ZWQgYnkgSWNvTW9vbi5pbyAtLT4KPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4KPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij4KPHBhdGggZmlsbD0iIzAwMDAwMCIgZD0iTTguNSAwbC0xLjUgMS41IDEuNSAxLjUtMy41IDRoLTMuNWwyLjc1IDIuNzUtNC4yNSA1LjYzNXYwLjYxNWgwLjYxNWw1LjYzNS00LjI1IDIuNzUgMi43NXYtMy41bDQtMy41IDEuNSAxLjUgMS41LTEuNS03LjUtNy41ek03IDguNWwtMS0xIDMuNS0zLjUgMSAxLTMuNSAzLjV6Ij48L3BhdGg+Cjwvc3ZnPgo=”);
color:#333333;
}

 

.c-callout–prerequisite{
border-color:#999999;
background-color:#ffffff;
background-image:url(“data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0ZWQgYnkgSWNvTW9vbi5pbyAtLT4KPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4KPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij4KPHBhdGggZmlsbD0iIzAwMDAwMCIgZD0iTTAgMXYxMGgxNnYtMTBoLTE2ek0xNSAxMGgtMTR2LThoMTR2OHpNMTAuNSAxMmgtNWwtMC41IDItMSAxaDhsLTEtMXoiPjwvcGF0aD4KPC9zdmc+Cg==”);
color:#333333;
}

 

 

.c-callout–important{
border-color:#f5b5ba;
background-color:#fff0f1;
background-image:url(“data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0ZWQgYnkgSWNvTW9vbi5pbyAtLT4KPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4KPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij4KPHBhdGggZmlsbD0iIzAwMDAwMCIgZD0iTTggMS41Yy0xLjczNiAwLTMuMzY5IDAuNjc2LTQuNTk2IDEuOTA0cy0xLjkwNCAyLjg2LTEuOTA0IDQuNTk2YzAgMS43MzYgMC42NzYgMy4zNjkgMS45MDQgNC41OTZzMi44NiAxLjkwNCA0LjU5NiAxLjkwNGMxLjczNiAwIDMuMzY5LTAuNjc2IDQuNTk2LTEuOTA0czEuOTA0LTIuODYgMS45MDQtNC41OTZjMC0xLjczNi0wLjY3Ni0zLjM2OS0xLjkwNC00LjU5NnMtMi44Ni0xLjkwNC00LjU5Ni0xLjkwNHpNOCAwdjBjNC40MTggMCA4IDMuNTgyIDggOHMtMy41ODIgOC04IDhjLTQuNDE4IDAtOC0zLjU4Mi04LThzMy41ODItOCA4LTh6TTcgMTFoMnYyaC0yek03IDNoMnY2aC0yeiI+PC9wYXRoPgo8L3N2Zz4K”);
color:#333333;
}

.c-callout–note{
border-color:#aecfc2;
background-color:#edf8f4;
background-image:url(“data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0ZWQgYnkgSWNvTW9vbi5pbyAtLT4KPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4KPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij4KPHBhdGggZmlsbD0iIzAwMDAwMCIgZD0iTTEzLjUgMGMxLjM4MSAwIDIuNSAxLjExOSAyLjUgMi41IDAgMC41NjMtMC4xODYgMS4wODItMC41IDEuNWwtMSAxLTMuNS0zLjUgMS0xYzAuNDE4LTAuMzE0IDAuOTM3LTAuNSAxLjUtMC41ek0xIDExLjVsLTEgNC41IDQuNS0xIDkuMjUtOS4yNS0zLjUtMy41LTkuMjUgOS4yNXpNMTEuMTgxIDUuNjgxbC03IDctMC44NjItMC44NjIgNy03IDAuODYyIDAuODYyeiI+PC9wYXRoPgo8L3N2Zz4K”);

color:#333333;
}

.c-callout–warning{
border-color:#fb0606;
background-color:#fff480;
background-image:url(“data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0ZWQgYnkgSWNvTW9vbi5pbyAtLT4KPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4KPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij4KPHBhdGggZmlsbD0iIzAwMDAwMCIgZD0iTTggMS40NWw2LjcwNSAxMy4zNjNoLTEzLjQwOWw2LjcwNS0xMy4zNjN6TTggMGMtMC4zNDUgMC0wLjY5IDAuMjMzLTAuOTUxIDAuNjk4bC02LjgyOSAxMy42MTFjLTAuNTIzIDAuOTMtMC4wNzggMS42OTEgMC45ODkgMS42OTFoMTMuNTgzYzEuMDY3IDAgMS41MTItMC43NjEgMC45ODktMS42OTFoMGwtNi44MjktMTMuNjExYy0wLjI2Mi0wLjQ2NS0wLjYwNi0wLjY5OC0wLjk1MS0wLjY5OHYweiI+PC9wYXRoPgo8cGF0aCBmaWxsPSIjMDAwMDAwIiBkPSJNOSAxM2MwIDAuNTUyLTAuNDQ4IDEtMSAxcy0xLTAuNDQ4LTEtMWMwLTAuNTUyIDAuNDQ4LTEgMS0xczEgMC40NDggMSAxeiI+PC9wYXRoPgo8cGF0aCBmaWxsPSIjMDAwMDAwIiBkPSJNOCAxMWMtMC41NTIgMC0xLTAuNDQ4LTEtMXYtM2MwLTAuNTUyIDAuNDQ4LTEgMS0xczEgMC40NDggMSAxdjNjMCAwLjU1Mi0wLjQ0OCAxLTEgMXoiPjwvcGF0aD4KPC9zdmc+Cg==”);
color:#333333;
}

.c-callout–caution{
border-color:#ffc266;
background-color:#ffebcc;
background-image:url(“data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0ZWQgYnkgSWNvTW9vbi5pbyAtLT4KPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4KPHN2ZyB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij4KPHBhdGggZmlsbD0iIzAwMDAwMCIgZD0iTTggMS40NWw2LjcwNSAxMy4zNjNoLTEzLjQwOWw2LjcwNS0xMy4zNjN6TTggMGMtMC4zNDUgMC0wLjY5IDAuMjMzLTAuOTUxIDAuNjk4bC02LjgyOSAxMy42MTFjLTAuNTIzIDAuOTMtMC4wNzggMS42OTEgMC45ODkgMS42OTFoMTMuNTgzYzEuMDY3IDAgMS41MTItMC43NjEgMC45ODktMS42OTFoMGwtNi44MjktMTMuNjExYy0wLjI2Mi0wLjQ2NS0wLjYwNi0wLjY5OC0wLjk1MS0wLjY5OHYweiI+PC9wYXRoPgo8cGF0aCBmaWxsPSIjMDAwMDAwIiBkPSJNOSAxM2MwIDAuNTUyLTAuNDQ4IDEtMSAxcy0xLTAuNDQ4LTEtMWMwLTAuNTUyIDAuNDQ4LTEgMS0xczEgMC40NDggMSAxeiI+PC9wYXRoPgo8cGF0aCBmaWxsPSIjMDAwMDAwIiBkPSJNOCAxMWMtMC41NTIgMC0xLTAuNDQ4LTEtMXYtM2MwLTAuNTUyIDAuNDQ4LTEgMS0xczEgMC40NDggMSAxdjNjMCAwLjU1Mi0wLjQ0OCAxLTEgMXoiPjwvcGF0aD4KPC9zdmc+Cg==”);
color:#333333;
}

.c-callout–important .c-callout__title{
color:#333333;
}

.c-callout–warning .c-callout__title{
color:#333333;
}

 

 

.c-callout–important,.c-callout–note,.c-callout–warning, .c-callout–caution, .c-callout–prerequisite, .c-callout–tip, .c-callout–info{
background-repeat:no-repeat;
background-position:24px 22px;
padding-left:50px;
}

/* end of css */ 

I’ll tell you where to add the CSS, but first let’s have a quick look at what each part of the CSS does.

The first c-callout, c-callout_title, and c-callout_paragraph styles set the defaults for the boxes. 

After those, there are styles for each type of “callout”, such as note, info, and warning. For each “callout” there is a border colour, a background colour, and a colour style (the colour style is for the colour of the text). There is also a background image, which you’ll see begins with url(“data:image/svg+xml; followed by a ton of gobbledygook. All of the code in this url reference is actually an SVG image that is converted to URI data.

There is an individual c.callout_title style for each “callout” too and these are for styling the word that appears above the text. For example, on a warning callout, the c.callout–warning c.callout_title style is for controlling the appearance of the word “warning”.

The block of code at the end is for setting the position of the icon image.

To use the CSS in your Zendesk:

  1. Copy the CSS above.
  2. Log in to Zendesk as an administrator.
  3. Click Guide
  4. Click the Customize Design icon (an eye icon).
  5. Edit your theme (View theme, and then Edit code).
  6. Select the file that contains the CSS for your Zendesk. This is usually called style.css. Zendesk shows you the code in the CSS file.
  7. Paste the CSS I have provided into your Zendesk CSS. 
  8. Click Publish

The CSS is now in place. Next, you need to know how to add the notes, warnings, cautions, etc., to your Zendesk articles. 

Add notes, warnings, cautions to your articles

To add the notes, warnings, cautions, etc., to your articles:

  1. Open an article.
  2. Click the Source Code icon to display the HTML of the article.
  3. Add the following code (For this example, I’ve included the code for an information box (info), but if you wanted a caution, just change c-callout c-callout–info to c-callout c-callout–caution. In the CSS, there are styles for info, caution, warning, note, important, prerequisite, and tip):

     

    <div class=”c-callout c-callout–info”>
    <strong class=”c-callout__title”>Enter the title of your callout here</strong>
    <p class=”c-callout__paragraph”>
    Enter the text for your callout here.
    </p>
    </div>

  4. Click OK to return to the normal view of the article. 
  5. Change the text for the note, warning, caution, to suit your requirements. When writing in Zendesk, the styles are not applied, so don’t be alarmed that there are no boxes or borders – they will appear in your help centre when you publish.
  6. When your article is finished, publish it. 

That’s all there is to it. But what if you want to create your own styles with different images? I’ll show you how to do that next.

Create your own styles

It’s pretty easy to create your own styles based on the ones I have provided. All you need to do is get a URI for an SVG icon and add some code to the CSS.

Generate a URI for an SVG icon

For the icon, you will need to get a 16x16px svg image. There are many available online and I used the free ones at IcoMoon

  1. Download the SVG image you are going to use. It must be svg format. Note that if you decide to use larger than 16x16px, you may need to change the spacing sizes in the CSS.
  2. Now you need to get the URI for the svg file. It is the URI that you add to the code in the CSS. I used dopiaza.org, so will explain how it works there.
  3. Upload your svg image.
  4. Choose Use base64encoding, Use User-Agent specified mime type, and then click Generate Data URI
  5. Copy the URI from the field. You are going to add that to your CSS in Zendesk.

Add a style to your CSS

 For your new style, you will need to add the following code to your CSS in Zendesk (swap out NAME OF YOUR STYLE GOES HERE for the name of your new style):

.c-callout–NAME OF YOUR STYLE GOES HERE{
border-color:#ffc266;
background-color:#ffebcc;
background-image:url(“THE URI CODE OF YOUR SVG ICON GOES HERE”);
color:#333333;
}

.c-callout–NAME OF YOUR STYLE GOES HERE .c-callout__title{
color:#333333;
}

If you wanted a new style called example box, you would change the first line to .callout–examplebox {  and so on. 

For the colours, you can change the hex values I have included to any colour that you want. For example, you could change color:#333333; to color:#f3f3f3; If you don’t know about hex colours for the web, see www.w3schools.com.

For the background image, paste the URI code for your SVG image. The URI needs to be enclosed in double-quotes ” “.

You also need to add the name of your new style to the block at the end:

.c-callout–important,.c-callout–note,.c-callout–warning, .c-callout–caution, .c-callout–prerequisite, .c-callout–tip, .c-callout–info, .c-callout–NAME OF YOUR STYLE GOES HERE{
background-repeat:no-repeat;
background-position:24px 22px;
padding-left:50px;
}

When you have made the changes, publish your CSS.

To use your style in your articles, open the source code of the article and add:

<div class=”c-callout c-callout–NAME OF YOUR STYLE GOES HERE”>
<strong class=”c-callout__title”>Enter the title of your callout here</strong>
<p class=”c-callout__paragraph”>
Enter the text for your callout here.
</p>
</div>

 

Over to you …

I hope this article has helped you to add notes, warnings, cautions, etc., to your Zendesk articles. Of course, it is only one way of doing it and there are others that you may prefer. As it is all CSS and SVGs, you could use the same approach to other web content too – I only used Zendesk as an example, because that’s what I was working on at the time.

Techncial Writer, Craig Wright

Craig Wright is an experienced technical writer based in Chesterfield, UK.  He hates writing about himself in the third person, so I shall stop now.

Always interested in new content writing opportunities. Remote working preferred.

Share This