-
Notifications
You must be signed in to change notification settings - Fork 24
Introductory articles outline
natashadsilva edited this page Oct 5, 2020
·
15 revisions
When announcing a new feature or component, here's a rough outline of what is needed. The focus of these articles is to give an overview of a new feature and not a step by step how-to.
A general thing to keep in mind when writing is:
- If I were a developer trying to find this article, what keywords would I be using to search for it?
- Are those keywords highlighted early in the article?
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. e.g.
- Preventing data loss in streaming applications is crucial for many industries. Streams has introduced a new consistent regions feature to guarantee that all data is processed at least once. In this article, I will discuss this feature, how it works, and how to use it.
- If you are a Streams developer using toolkit A to compute XYZ, you might want to do DEF. Previously this wasn't possible but now you can with the new ...
If there is any background information they need to understand this article, mention it here and provide links.
Bit more detail in the tool. Organize your article around the following points:
- What does a reader need to know about this feature?
- What are the key takeaways?
- 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.
- 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?)
Link to any other content (Articles, Knowledge center) that dive deeper.