• In this page we would like to share some ideas how to write an article.
• We are aware of the fact that most articles in this site currently wouldn't match these requirements. 
• Let's put it like this: there is always room for improvement and the following chapters are intended as a guideline for constant improvement towards a better knowledge base.

Before you start writing

Find out about existing standards

• Consider the Technical Writing Guide
• Consider the Style Guide

Verify to what extent your topic is covered by existing articles

• The Product Knowledge Base contains some hundred articles. Chances are good that your topic is covered by some other article.
• Help us to avoid duplicate articles. Take a deliberate decision if it were better
  • to modify an existing article in order to make it more accurate and more complete or
  • to add a new article that would reference existing resources.

Where to look for existing articles?

• Usually the How To sections and the FAQ sections would contain information to almost every topic.
  • However, that information might not be complete or might not be presented in a consistent manner.
• Use search terms to verify specific keywords in existing articles.

How to reference existing articles?

• Add a chapter See also to the end of your article.
• Add the list of existing articles to that chapter.

Design your article for a public audience

• Consider that your audience will consist of developers, power users, customers and newbies with a mixed background. 
• Try to make your topic understandable for a broader audience - at least in the initial section of the article so that everybody has a fair chance to understand what it is about.
• It's fine if your article is addressed e.g. to an advanced audience. However, don't forget to mention this fact in the initial section.

When it comes to writing

Clearly state your topic

• if you want to publish a solution that you found then don't forget to mention the problem that you solved.

Define the scope

After writing

Have someone review your article

• It is always a good idea to have someone review your article.
• Receiving a second opinion might help to discover aspects of topic that were out of your radar.
  • Use the share operation that is available on every page to invite other users for review.

Accept feedback

• This site provides some mechanism for ratings and surveys.
• Feedback is not necessarily about receiving applause. Never take a negative feedback personal and never discuss with posters.
  • Feedback presents someone's perception of an article and therefore is neither right nor wrong. 
  • Instead, try to understand what problem has been perceived and if you could accept to modify your article to comply with the poster's perception.

Never stop improving

• So you think you're done having received some feedback on your article? Definitely not.
• Articles tend to become inaccurate and even obsolete by ageing.