(DOCSP-4936) added info ab metadata tags #118
Conversation
| ============= | ||
| Metadata | ||
| ============= |
There was a problem hiding this comment.
I think the over/under tags here (the lines of equal signs) should be the same length as the word "Metadata"
| Use ``.. meta::`` to add meta tags to a page. Adding meta tags aids in | ||
| searches both internally and via the Internet. | ||
|
|
||
| .. code-block:: rst |
There was a problem hiding this comment.
Can we put a subheader here that marks this as an Example? I can understand it just fine, but that's the pattern Kailie and I have been following.
| .. meta:: | ||
| :description: read concern, local read concern, read isolation, | ||
| transactions, multi-document transactions |
There was a problem hiding this comment.
Do we have any information on which meta tags are available and when to use each one? Even a link to that info would be useful here.
| .. code-block:: rst | ||
|
|
||
| .. meta:: | ||
| :description: read concern, local read concern, read isolation, |
There was a problem hiding this comment.
I feel like we should explain what :description: means here. Is it required? What is its purpose?
| .. include:: /includes/styles/corrections.rst | ||
|
|
||
| Use ``.. meta::`` to add meta tags to a page. Adding meta tags aids in | ||
| searches both internally and via the Internet. |
There was a problem hiding this comment.
Can we go into a bit more detail about what "aids in searches" means? For example, perhaps we could add a sentence that says something like:
"When users search for terms defined in meta tags, pages with those tags are given higher priority in search results."
Note that the wording could probably be improved here, but I think something that gets a bit more specific about how these tags impact searches would be helpful.
There was a problem hiding this comment.
I think adding the following information would be helpful:
- MDN link to explain meta tags https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
- An example of how it would render to HTML
- A link to how Google uses meta html tags
| .. meta:: | ||
| :description: read concern, local read concern, read isolation, | ||
| transactions, multi-document transactions | ||
|
|
There was a problem hiding this comment.
Possible future work:
It might be worth reaching out to one of our SEO experts for guidance on effective meta tags. For example, should we avoid repeating words across multiple tags? Are there any helpful guidelines to be aware of?
There was a problem hiding this comment.
I think we have a document for this already, just need to find and link it.
There was a problem hiding this comment.
@ccho-mongodb, Cloud uses this guidance to improve SEO with meta tags. I think we should generalize and incorporate this content.
There was a problem hiding this comment.
Sure, I think it makes sense to expand the content, but as Jeff mentioned, separate from this review. I think that document looks great. I'm appending some info at the end from a related discussion I had with Docs Platform a few months ago.
| @@ -0,0 +1,19 @@ | |||
| .. _metadata: | |||
There was a problem hiding this comment.
I notice that this page does not appear to be in the TOC. Is this intentional?
There was a problem hiding this comment.
I found a few issues with this page. We should edit the existing page and incorporate this guidance. Also, the original example says :description:, but actually, it should be :keywords:.
| .. meta:: | ||
| :description: read concern, local read concern, read isolation, | ||
| transactions, multi-document transactions | ||
|
|
There was a problem hiding this comment.
@ccho-mongodb, Cloud uses this guidance to improve SEO with meta tags. I think we should generalize and incorporate this content.
| .. _metadata: | ||
|
|
||
| ============= | ||
| Metadata | ||
| ============= | ||
|
|
||
| .. default-domain:: mongodb | ||
|
|
||
| .. include:: /includes/styles/corrections.rst | ||
|
|
||
| Use ``.. meta::`` to add meta tags to a page. Adding meta tags aids in | ||
| searches both internally and via the Internet. | ||
|
|
||
| .. code-block:: rst | ||
|
|
||
| .. meta:: | ||
| :description: read concern, local read concern, read isolation, | ||
| transactions, multi-document transactions | ||
|
|
There was a problem hiding this comment.
We should edit the existing page instead of adding this new one.
| .. _metadata: | |
| ============= | |
| Metadata | |
| ============= | |
| .. default-domain:: mongodb | |
| .. include:: /includes/styles/corrections.rst | |
| Use ``.. meta::`` to add meta tags to a page. Adding meta tags aids in | |
| searches both internally and via the Internet. | |
| .. code-block:: rst | |
| .. meta:: | |
| :description: read concern, local read concern, read isolation, | |
| transactions, multi-document transactions | |
| .. _metadata: | |
| ======== | |
| Metadata | |
| ======== | |
| .. default-domain:: mongodb | |
| Use ``.. meta::`` to add |html| meta tags to a page. Adding meta tags aids in | |
| searches both internally and via the Internet. You can add both keywords and descriptions. | |
| .. code-block:: rst | |
| .. meta:: | |
| :keywords: read concern, local read concern, read isolation, transactions, multi-document transactions | |
| :description: You can tune the consistency and availability of your application using write concerns and read concerns. | |
| Add the ``.. meta::`` directive on the line below the ``.. default-domain::`` directive with a line break in between. | |
| Keywords | |
| ---------- | |
| - Take the most concise form of the information that the page conveys and make that | |
| the target keyword. | |
| - Don't add keywords so broad that they compete with the product page. | |
| - Don't add keywords so specific that we miss the actual behavior of our searchers. | |
| For example, add “mongodb atlas course” instead of | |
| “Getting Started with Atlas Data Platform”. | |
| Descriptions | |
| ------------- | |
| - Write the snippet that appears under the link in the search results. | |
| - Make the descriptions informative (and enticing if possible). | |
| - Emphasize the “why” for using the page. | |
| - Use a maximum of 155 characters . | |
| - Include target keyword and a call to action. | |
| - Keep the description short, simple and concise. | |
| - Concisely explain what the page is about. | |
| - Use unique meta descriptions for every page. | |
| **Examples:** | |
| .. code-block:: rst | |
| .. meta:: | |
| :description: Use a language analyzer to create search keywords in your Atlas Search index that are optimized for a particular natural language. | |
| .. code-block:: rst | |
| .. meta:: | |
| :description: Use the character filters in an Atlas Search custom analyzer to examine text one character at a time and perform filtering operations. | |
There was a problem hiding this comment.
I agree that we should use the existing page because the basic information about the tag is relevant in the "markup/directives" section, but the additional info that provides guidance seems beyond the scope of the rest of the content in that section. For example, see the content in markup/directives/code-blocks.txt.
I think we should do the following:
- fix up the description of the directive in this PR
- in a future task, create a new page (e.g. "Meta Tag Guidelines") that provides guidance on similar to the Error Message Guidelines page.
- add a link from this page to the new one
|
Hi @carriecwk , I just wanted to check in on this PR to see if you had seen the review feedback. Please respond when you get the chance! |
JIRA
Stage
Build