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?