• 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 on 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 the starting situation

• if you want to publish a solution that you are proud to have invented then don't forget to mention the underlying problem that you solved.
• A good approach is to start an article by clearly stating a problem:
  • Most problems stem from user expectations that have not been met. 
  • In other words, clearly state the gap between user expectations and the effective behavior of the product.
• A perfect approach is to elaborate the user requirements in your article. This sounds simple, but in fact it is not:
  • Most users would tell us what they want, not what they need. 
  • There's a subtle difference between these terms: 
    • Users who request a functionality tend to suggest some solution how a function or operation should work. This is what they want.
    • Users who describe their usage scenario state what they would like to achieve. This is what we call a user story and is a functional requirement.
  • Development of a solution always starts with valid requirements, not with a wish list. There is no chance in developing a sustainable solution when skipping the requirements elaboration.
  • If the solution that you describe in your article would not satisfy all thinkable requirements then this is not a disaster. At least if you clearly state to what extent the solution meets the requirements of the starting situation.

Define the scope

• The scope of the solution that you describe in your article should be clearly sized concerning
  • the type of problem that the solution is applicable for,
  • the extent to that requirements will be met and
  • the limitations that apply.
• Scoping should include the information for what releases of a product the solution is applicable, e.g. starting from version ...

Be specific

• There might be implications of the solution that you describe that are absolutely clear to you. However, this is not necessarily true for your audience.
  • For example when it comes to stating locations for files then you should better state the complete path instead of relying on the fact that every user knows where to locate that file.
• When using technical terms then try to use the correct ones;
  • Do not invent new terms for existing facts. We know of features that were described in misleading terms and ended up in contradictions.
  • Stick to exact wording. Use the accepted wording for a fact that you describe and try not to change that wording for some fancy new expression. Recurring terms might make articles a bit more boring to read, however, they will improve the accuracy of the description as everybody clearly knows to what you relate.
  • The knowledge base is added a Glossary for commonly used terms. Please use it in order to verify existing terms and to add new terms of common interest.

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.
  • The famous saying that there is more than one way how to do it, is particularly true for our products.
  • Use the share operation that is available on every page in the knowledge base to invite other users for review.
  • Add two possible labels to your page:
    • review-editing: to have someone review language use in the page.
    • review: to have someone review the technical content of the page

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 aging. This might be due to newer versions of the product or updates to the environment.
• Therefore add an expiration date to your article, e.g. for six months later. When that time has come then you will be notified by mail that your article has to be reviewed or otherwise will be marked as invalid.
  • At the time of writing articles are automatically proposed for review one year after the last update.
  • Specify an individual expiration date by adding to your page a label with the name expire-single-yy/mm/dd, e.g. expire-single-15/02/28 to get notified by end of February 2015.