Stay organized with collectionsSave 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-sat 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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-10-15 UTC."],[[["\u003cp\u003eWhen writing documentation for methods, focus on what the method accomplishes (e.g., "creates") rather than the developer's action (e.g., "create").\u003c/p\u003e\n"],["\u003cp\u003eThis subtle difference is mainly reflected in whether the initial verb in the description is singular or plural, with the singular form being preferred.\u003c/p\u003e\n"],["\u003cp\u003eRefer to Google Cloud API design guide for further details and illustrations.\u003c/p\u003e\n"]]],["Method descriptions in reference documentation should focus on the method's actions, using verbs with an \"-s\" ending. This means describing what the method *does* (e.g., *creates*, *lists*) rather than what the developer *would do* with it (e.g., *create*, *list*). For example, \"Creates a new task\" is preferred over \"Create a new task.\" This convention enhances clarity and consistency in API documentation. Refer to the Google Cloud API design guide for further details.\n"],null,["# Verb forms in reference documentation\n\nWhen you're writing reference documentation for a method, phrase the main\nmethod description in terms of what the method does (*gets* , *lists* , *creates* ,\n*searches* ), rather than what the developer would use it to do (*get* , *list* ,\n*create* , *search*).\n\nIt's a subtle distinction that manifests mostly in whether the initial verb\nin the description has an *-s* at the end or not.\n\nRecommended: tasks.insert: Creates a new\ntask on the specified task list.\n\nNot recommended: tasks.insert: Create a\nnew task on the specified task list.\n\nFor more information and examples, see the\n[Google Cloud API design guide](https://cloud.google.com/apis/design/documentation#method_description)."]]
