Ensure API documentation, including changelogs and feature descriptions, prioritizes user understanding over implementation details. Write descriptions that explain what users can expect from the API behavior rather than how it’s technically implemented. Avoid redundant information when context is already established (e.g., don’t repeat “language server feature” under a “Server” section). Provide proper references and links to specifications or external documentation when mentioning technical concepts.
Example improvements:
Write: “Prefer the runtime definition, not the stub definition, on a go-to-definition request for a class or function”
This approach makes API documentation more accessible to users who need to understand functionality and behavior, not internal implementation choices.
Enter the URL of a public GitHub repository
