fix(manifest): Update manifest member pages to follow the same format #35557
Conversation
There was a problem hiding this comment.
It looks very nice! Much more consistent and readable now 😍
I have a small concern, though.
```json
"screenshots": [
{
"form_factor": "narrow" | "wide"
}
]
```Presenting values in the code examples separated by pipes looks clear if you know how JSON works, how strict it is, etc. But when you’re learning about manifest for the first time, you might just copy-paste the sample and have a hard time figuring out why your manifest doesn’t work. Browsers won’t show you any warnings if your manifest is malformed.
I searched for true | false kind of cases, and they’re not very common, apart from XSL docs, for example. We can fix this, too. I’ll bring this up on the next content sync. Or you can do it while I’m away :)
I wonder if it would be better to show some sort of obviously non-fitting placeholder with the value type and list values below? These are pretty common on MDN. Something like:
```json
"screenshots": [
{
"form_factor": <string>
}
]
```
- `"narrow"` some desc
- `"wide"` some desc
|
Thanks for reviewing, @pepelsbey! You've highlighted how we approach Syntax sections across different technology areas on MDN. :) Some background on how I went about the syntax on these pages: I wanted to add a "Syntax" section that provides a quick, sort of a scannable, template that lists all available values or property-value pairs, including any keyword values, so readers can get an overview at a glance. For style, I aligned it with the JS and API areas, using camelCase variables in the syntax, rather than following the approach in the CSS area of using examples to demonstrate the syntax. I see your point about the potential confusion from using the If we skip the keywords in the syntax, we could use the variable name to suggest that specific keywords are expected as values for the said member/property. Combining this idea with your suggestion, we could use: ```json
"screenshots": [
{
"form_factor": "keywordValue",
"platform": "keywordValue"
}
]
```and I'd considered using placeholders like Update: In CSS, we do use the Another update: Resorting to use the |
There was a problem hiding this comment.
@pepelsbey, I've suggested these changes to remove the pipe notation and streamline some other variable names.
|
This pull request has merge conflicts that must be resolved before it can be merged. |
|
Hi Vadim, this is ready for you to take another look. Thanks! |
|
Moving this to draft until we decide on a format in #34725 |
|
This pull request has merge conflicts that must be resolved before it can be merged. |
github-actions
bot
added
size/m
|
Hi @pepelsbey, we reached a consensus in #34725 (comment) about the format of "Syntax" blocks. It will contain use cases, similar to the "Syntax" blocks in CSS properties, not placeholder variables. What you need to know for reviewing this PR:
|
Description
Issue: At the moment, the manifest member pages lack consistency: some list values in a table, while in some others, the "Values" section appears after "Examples" or uses a longer section name like "launch_handler item values".
Goal: Before updating the content of individual manifest member pages, I want to align them all so that they have the same sections in the same order and follow the same format.
Changes in this PR:
Next steps: I haven't made any content updates yet (except for adding the Syntax section), so some pages do not have a "Values" section at this point. I'll tackle this in my next iteration.
Motivation
To standardize the structure and format across manifest member pages
Related issues and pull requests
displaypage PR: docs(manifest): Improvedisplaymember page #34386iconspage PR: docs(manifest): Improveiconsmember page #34725