We write 2 kinds of content: structured and unstructured. Most of our technical and educational documents are structured, following standardized content templates. These templates make both writing and reading easier. They also help future-proof our documents, making it easier for developers to come in later and add semantic data to make the work reusable outside of where it was originally published.
This section lays out when to use a structured content template and how to create a template of your own.
While some content types are better served by a unique structure created by the writer, others lend themselves to a reusable structure. Blog posts, newsletter content, and most marketing copy are all examples of unstructured content that will vary from piece to piece. The more reusable your content might be, the more helpful a content template will be.
Consider using a template if:
- Readers benefit from seeing your content multiple places
- Readers need to scan it
- Writers need to create similar content more than once or twice
- You want to encourage repeat visits and familiarity with your content
All educational content relies heavily on content templates. We use templates for Technical Content, Integration Directory descriptions, marketing guides, and more.
If you’re looking for a template for your structured content but can’t find one that meets your needs, you may want to create your own. There are 2 main ways to create a new template.
Use a model
If you already have a piece of content that serves its purpose well, use it as a model. Review some of the templates in the style guide to see how granular you might want to get, and look for any elements you might want to add.
As you read through the model document, make a list of all the individual parts that make up the piece. Then briefly describe what they do and how they do it.
Common elements in templates are:
- Body content (which can usually be broken apart into smaller elements)
- Additional links
Keep in mind that the template has to be reusable. So, it’s best to focus on the high-level goal of the content type, rather than the message of a particular piece.
Start from scratch
If you like outlining before you write, that’s a great way to start your template. Outlining will give you an early look at the elements you’ll include in your final template and will help organize your writing process.
You may prefer to write a draft first, then outline later based on how the parts fit together. Read your draft closely and identify the important elements or patterns you’ve used. Looking for things like introductions, sections with headings, tables, images, and other elements that aren’t topic-specific. Write them out and describe how they inform the meaning or usability of the piece.
Create your template by listing out the elements you identify in your outline or draft. Consider each element and what it contributes to the meaning of the piece. Is its purpose important enough that every content of this type should include it? If so, make it part of your template.