Skip to content

Introductory articles outline

natashadsilva edited this page Jan 16, 2017 · 15 revisions

When announcing a new feature or component, here's a rough outline of what is needed. This is similar to the task based guide recipe but the focus of these articles is different. Instead of a detailed step by step, it is more a high level introduction.

Problem statement: General, user-focused statement(s) describing the problem or need that the new toolkit or component addresses and the benefit they gain from using it. What will this article talk about?

Prerequisites: (optional) If there is any background information they need to understand this article, mention it here and provide links. What do they need in order to run this tool? How do they get it?

Overview Bit more detail in the tool. How does it work, without going into too much detail? E.g "This tool provides a set of REST endpoints to allow you to ...". If there are other alternatives, or similar solutions or tooling, mention these and help the user see when they would use this new tool instead of the existing component. Help them choose. Mention its features and the problems they solve.
Avoid discussing interesting, but unnecessary details about the component.

Get started Show how to get set up (install/config) A couple of simple examples of usage and common configuration options Common troubleshooting (what errors might they run into?)

What next to do Link to any other content (Articles, Knowledge center) that dive deeper.

Clone this wiki locally