Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • Usually the How To sections and the FAQ sections would contain information to 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.

...

  • 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

...