Add a clear overview of summary vs description #130
Conversation
| Many objects support both `summary` and `description` fields, and this is especially useful where documentation or other tools might show items in either list or detail view. | ||
|
|
||
| - `summary` is used for list view, and should be kept short. A single-sentence summary works well. | ||
| - `description` is shown when the item is being viewed in detail. The descriptions support markup and give you space to include as much information for your users as you want to. Don't be afraid to add paragraph breaks, links, or even bullet lists in these fields. |
There was a problem hiding this comment.
I would be tempted to make this more determistic from the perspective of what Markdown supports i.e.
"CommonMark supports formatted text, so their is an opportunity to provide extensive, explanatory text in the description property that can be rendered by tools that support OpenAPI."
And then break into "do not..."
Doing this sets the constraints of the language, before providing advice on best practice.
There was a problem hiding this comment.
I'm happy to edit, but we're already going on a lot about the actual markdown aspect in this article. I am mostly trying to explain how the fields are used, since that information wasn't clear.
|
I'm merging rather than abandoning as I'm not really sure how to make the suggested changes. Let's track further amendments in an issue/ |
lornajane
deleted the
129-new-article-best-practices-for-summary-and-description
branch
Fixes #129 after we talked about these two fields in a TDC meeting.