Configuration documentation should be precise, specific, and include helpful context for users. Avoid vague or ambiguous language that could lead to misunderstanding of how settings behave.
Configuration documentation should be precise, specific, and include helpful context for users. Avoid vague or ambiguous language that could lead to misunderstanding of how settings behave.
Key principles:
For example, instead of writing:
Paths passed explicitly are checked even if they are otherwise ignored by an exclude or ignore file.
Write:
Paths that are passed as positional arguments to `ty check` are included even if they would otherwise be ignored through `exclude` filters or an ignore-file.
Similarly, when explaining pattern matching behavior, be explicit about anchoring:
Include patterns are anchored: The pattern `src` only includes `<project_root>/src` but not something like `<project_root>/test/src`. To include any directory named `src`, use the `**/src` prefix match.
This approach helps users understand exactly how configuration options will behave in their specific use cases and reduces confusion about expected vs. actual behavior.
Enter the URL of a public GitHub repository