Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

(DOCSP-4936) added info ab metadata tags #118

Open
wants to merge 6 commits into
base: feature-skunkworks
Choose a base branch
from
Open

(DOCSP-4936) added info ab metadata tags #118

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5937048
(DOCSP-4936) added info ab metadata tags
carriecwk Jul 20, 2022
8fed343
(DOCSP-4936) added a space to push again
carriecwk Jul 21, 2022
1b3ae99
(DOCSP-4936) added a space to push again
carriecwk Jul 21, 2022
45ea5f4
(DOCSP-4936) added a space to push again
carriecwk Jul 21, 2022
7f51f8d
(DOCSP-4936) added a space to push again
carriecwk Jul 21, 2022
146d99d
(DOCSP-4936) eliminated bullet point in description
carriecwk Jul 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions source/style-guide/style/metadata.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
.. _metadata:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I notice that this page does not appear to be in the TOC. Is this intentional?


=============
Metadata
=============
Comment on lines +3 to +5
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the over/under tags here (the lines of equal signs) should be the same length as the word "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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think adding the following information would be helpful:


.. code-block:: rst
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like we should explain what :description: means here. Is it required? What is its purpose?

transactions, multi-document transactions
Comment on lines +16 to +18
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we have a document for this already, just need to find and link it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ccho-mongodb, Cloud uses this guidance to improve SEO with meta tags. I think we should generalize and incorporate this content.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +1 to +19
Copy link
Contributor

@corryroot corryroot Dec 15, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should edit the existing page instead of adding this new one.

Suggested change
.. _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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. fix up the description of the directive in this PR
  2. in a future task, create a new page (e.g. "Meta Tag Guidelines") that provides guidance on similar to the Error Message Guidelines page.
  3. add a link from this page to the new one

3 changes: 1 addition & 2 deletions worker.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1 @@
#!/bin/sh
make html
"build-and-stage-next-gen"