- A pattern can be different things to different people.
- People with different backgrounds require different amounts of detail.
- Using too much audience-specific jargon may limit the potential audience.
- Diagrams and illustrations are often more effective than prose when it comes to communicating concepts, especially those related to software design. "A picture is worth a thousand words."
- Programming languages are designed to convey software concepts in a formal, precise, and unambiguous manner.
- Too much code interrupts the pattern's flow and may make it unmanageably large.
- There is no universally understood programming language. Code Samples will be understood only by those readers who are familiar with the language you use.
- Use terminology that is tailored to the audience.
- Include a Glossary of terms which may be unfamiliar.
- Use diagramming notations that are likely to be familiar to the target audience.
- Use a programming language likely to be understood by the Target Audience.
- Ensure that the code samples are well-commented.
- Ensure that your code samples are "ready to run".
- Ensure that the pattern can stand on its own, able to communicate its essential concepts even if the code examples were deleted.