Verb forms in reference documentation

Stay organized with collections Save and categorize content based on your preferences.

When you're writing reference documentation for a method, phrase the main method description in terms of what the method does (gets, lists, creates, searches), rather than what the developer would use it to do (get, list, create, search).

It's a subtle distinction that manifests mostly in whether the initial verb in the description has an -s at the end or not.

Recommended: tasks.insert: Creates a new task on the specified task list.

Not recommended: tasks.insert: Create a new task on the specified task list.

In a specification that's aimed at implementors of an API, it may make more sense to use the verb form without the -s. In that context, you're telling the reader what their implementation of the method should do (create a new task), whereas in reference docs aimed at developers, you're telling them what the existing method does (creates a new task).