API Reference method page template - add description #36185
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
hamishwillee
requested review from
chrisdavidmills
and removed request for
a team
github-actions
bot
added
Content:Meta
|
Preview URLs (comment last updated: 2024-10-06 20:50:08) |
OnkarRuikar
reviewed
Oct 4, 2024
...en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md
Outdated
Show resolved
Hide resolved
OnkarRuikar
reviewed
Oct 4, 2024
|
|
||
| _Detailed description of how the method behaves_ | ||
| _Section omitted if an introductory paraphgraph (or two) at the top of the page are sufficient._ | ||
|
|
There was a problem hiding this comment.
Suggested change
| _Tips and quirks about the method._ | |
I always wonder if quirks, notes, warnings, and tips should be in the intro section or the description section.
There was a problem hiding this comment.
Description, I'd say.
There was a problem hiding this comment.
Yes, but I don't think we need to mention this specifically - the would clearly be part of an extended description.
chrisdavidmills
approved these changes
Oct 4, 2024
...en-us/mdn/writing_guidelines/page_structures/page_types/api_method_subpage_template/index.md
Show resolved
Hide resolved
…api_method_subpage_template/index.md Co-authored-by: Onkar Khadangale <87750369+OnkarRuikar@users.noreply.github.com>
|
Thanks for the reviews gents. I'm merging the fix, and ignoring the extra suggestions in order to keep things simple |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This adds a "Description" heading to the API ref page template for methods.
FWIW I think we should not be too concerned about this - if you can create an adequate description in 3 or 4 paragraphs up the top of the page then that is better for users than having to navigate down to another section for detail. On the other hand, if it is a much bigger section, it makes sense to push it below the fold so people can jump to the detail earlier.
However if this exists it should be in this position.