Often developers (or other technical people) have to adhere, comply or obey to concepts. Therefore understandability, clarity, and applicability are primary goals, together with a shot of consistency, of course.

Some rules you should apply:

  • Be practical and use source code examples to explain and demonstrate. Automated test can accompany the plain code, giving developers a feel how to do things.
  • Write your concepts in the form of developer use cases”: “A developer wants to achieve XYZ” - and explain step by step what people have to do.
  • Explain reasons why the concept is like it is. If you deviate from established standards or procedures, explain why and how you came to your solution.
  • You can combine text with static and dynamic diagrams to describe your more complicated concepts.
  • Describe the applicability: In which or for what cases shall the concept be applied?
  • Describe the limits: In what cases, under which circumstances will the concept fail or cease to work?