Always define technical terms and concepts explicitly in documentation rather than assuming reader knowledge. Avoid ambiguous phrasing that could be interpreted multiple ways.
When introducing technical terms:
Examples of good practice:
# Good: Clear definition
* `.trailers() -> List<Trailer>`: The trailers at the end of the commit
description that are formatted as `<key>: <value>`.
# Bad: Ambiguous phrasing
* `.trailers() -> List<Trailer>`: The trailers at the end of the commit
description, formatted as `<key>: <value>`.
# Good: Precise terminology
* `.synced() -> Boolean`: For a local bookmark, true if synced with all tracked remotes.
# Bad: Imprecise terminology
* `.synced() -> Boolean`: For a local bookmark, true if synced with all remotes.
This prevents confusion, reduces the need for readers to maintain external references, and ensures documentation is self-sufficient. Pay special attention to terms that may have different meanings in different contexts or tools.
Enter the URL of a public GitHub repository