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.

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

docs: add seo guide #1059

Open
wants to merge 52 commits into
base: master
Choose a base branch
from
Open
Changes from 5 commits
Commits
Show all changes
52 commits
Select commit Hold shift + click to select a range
8f17680
docs: add seo guide
CBID2 Feb 9, 2024
995f474
feat: finish section on S
CBID2 Feb 9, 2024
a59d5e2
feat: add frontmatter
CBID2 Feb 9, 2024
30b0dbd
fix: omit heading 1
CBID2 Feb 9, 2024
29c82a2
Merge branch 'master' into seo-guide
quetzalliwrites Feb 13, 2024
5b9d282
feat: made improvements in the sections about SEO and headings
CBID2 Feb 16, 2024
873c3d7
feat: revise sections about URL and alt text
CBID2 Feb 16, 2024
ea636c0
feat: add examples of SEO-friendly URLs
CBID2 Feb 16, 2024
02c1621
feat: add section for other ways to make Asyncapi's documentation SEO…
CBID2 Feb 16, 2024
b038d16
Merge branch 'master' into seo-guide
CBID2 Feb 16, 2024
4dd2cbe
Merge branch 'master' into seo-guide
quetzalliwrites Feb 21, 2024
0ab1ee6
fix: remove addtional suggestions section
CBID2 Feb 22, 2024
a290e30
fix: omit bullet point
CBID2 Feb 22, 2024
1043e2d
fix: revise typos
CBID2 Feb 22, 2024
c5c2cb3
feat: created section for Anchor text
CBID2 Feb 22, 2024
e36abe0
feat: add explanation on what makes URL examples SEO-friendly
CBID2 Feb 29, 2024
dc7e656
feat add tips on making SEO-friendly anchor texts and a section for e…
CBID2 Feb 29, 2024
97ddcac
Merge branch 'master' into seo-guide
CBID2 Feb 29, 2024
f69a121
feat: add examples of SEO-friendly anchor texts
CBID2 Mar 3, 2024
cd32a5d
Merge branch 'master' into seo-guide
CBID2 Mar 3, 2024
91a9ba2
fix: revise meta description
CBID2 Mar 3, 2024
4d6a15f
feat: add explanation about what makes the example anchor text SEO-fr…
CBID2 Mar 3, 2024
ccbd863
fix: revise Markdown errors
CBID2 Mar 3, 2024
67082d4
Merge branch 'master' into seo-guide
CBID2 Mar 11, 2024
3810936
Merge branch 'master' into seo-guide
CBID2 Mar 13, 2024
a3d1deb
feat: add some comments
CBID2 Mar 13, 2024
1dc4c41
feat: finished adding more detail about headings and start another se…
CBID2 Mar 31, 2024
ae9d05d
feat: added new sections
CBID2 Mar 31, 2024
27225f7
fix: omit comment and revise markdown formatting
CBID2 Mar 31, 2024
100f76f
fix: revise headings
CBID2 Apr 1, 2024
6385f00
feat: finished section on meta descriptions
CBID2 Apr 1, 2024
4a75db2
Merge branch 'master' into seo-guide
CBID2 Apr 1, 2024
00944f1
feat: revise structure
CBID2 Apr 1, 2024
129986f
fix: remove period
CBID2 Apr 1, 2024
0f21cb8
docs: finished adding information about mobile and SEO-friendly techn…
CBID2 Apr 3, 2024
93580b4
docs: add Additional resources section
CBID2 Apr 3, 2024
8629680
docs: fix formatting issues
CBID2 Apr 3, 2024
c9c1068
Merge branch 'master' into seo-guide
CBID2 Apr 18, 2024
518fb48
docs: add section on image optimization
CBID2 Apr 18, 2024
3f67568
Merge branch 'master' into seo-guide
CBID2 May 26, 2024
21c7e1c
docs: made edits
CBID2 May 26, 2024
f551555
docs: fix explanation
CBID2 Jun 2, 2024
11a7898
Merge branch 'master' into seo-guide
CBID2 Jun 2, 2024
1e90fb7
Merge branch 'master' into seo-guide
CBID2 Jun 4, 2024
f3dc224
docs: revise description
CBID2 Jun 5, 2024
7bc89d6
Merge branch 'master' into seo-guide
CBID2 Jun 16, 2024
7c77e38
docs: change sentence
CBID2 Jul 1, 2024
c29c022
Merge branch 'master' into seo-guide
CBID2 Jul 1, 2024
8fde226
fix: revise errors
CBID2 Jul 1, 2024
8b21d9c
Merge branch 'master' into seo-guide
CBID2 Jul 14, 2024
18cb74d
Merge branch 'master' into seo-guide
CBID2 Jul 16, 2024
8d26291
Merge branch 'master' into seo-guide
CBID2 Oct 27, 2024
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
38 changes: 38 additions & 0 deletions docs/styleguide/seo.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
Copy link
Member

Choose a reason for hiding this comment

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

📣 Feedback for Draft 1

What is SEO?

The definition is accurate but could be slightly rephrased. For example, "SEO (Search Engine Optimization) refers to the methods and strategies used to enhance the visibility of a website's content in search engine results."

Why is it important in our Documentation?

Could you add a sentence about the potential for increased contributions and community growth through effective SEO?

Headings

  • The phrase "chronological order" is confusing because we're not discussing time. It's clearer to say, "hierarchical order".
  • Include an example of headings.

Alt Text

  • The phrase "avoid writing add every single detail" has a typo. It could be corrected to "avoid writing down every single detail."
  • Include an example of good alt text.

URLs

  • The guidance is generally good but simplifying the explanation could make it more accessible. For instance, "Use hyphens (-) instead of underscores (_) to separate words in URLs, as search engines treat hyphens as space."
  • Add examples of well-structured URLs from our different content buckets such as: asyncapi.com/docs/concepts/server

Additional Suggestions

  • Meta Descriptions: Our current docs and blog posts all use meta descriptions and titles. These summaries appear under the title in search results and can significantly impact click-through rates.
  • Mobile-Friendliness: Mention the importance of ensuring that documentation is mobile-friendly, as this is a factor in search engine rankings.
  • Internal Linking: Encourage the use of internal linking to other parts of the documentation or the AsyncAPI website to boost SEO and user navigation.
  • Content Quality: Emphasize the importance of high-quality, original content. Search engines favor content that provides value to users.
  • Anchor Text:
    • Be descriptive and relevant.
    • Avoid generic phrases like "click here" or "this page". (Instead, use meaningful phrases that give users and search engines an idea of what to expect on the linked page.)
    • Vary your anchor text. While it's important to be descriptive, using the exact same anchor text for every link to a particular page can appear spammy to search engines. Try to vary the phrasing while still being clear about the page content.

title: SEO
description: This guide gives advice on how to implement SEO when creating tutorials for our project.
---

## What is SEO?

SEO (Search Engine Optimization)is the use of methods and strategies to ensure that a website's online content shows up when people search for them.

### Why is important in our Documentation?
Copy link
Member

Choose a reason for hiding this comment

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

Hey there, just a reminder that we observe sentence capitalization in headers. Please update and correct all headers accordingly :)

Copy link
Member

Choose a reason for hiding this comment

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

A reminder that the doc should be written to the audience via "you", not "we." Please go through your doc and update all mentions accordingly.


Implementing SEO practices would make it easier for our users and others to find them.

### SEO Best Practices

#### Headings

Headings are tags used to make sub titles distinctive from each other. When it comes to making them SEO-friendly, it's highly recommended to do the following:

- **Put them in chronological order:** Since an `h1` tag tend to be titles, always start with this tag. From there, use `h2` and`h3` tags for the subsections and `h4` and `h5` tags for other sections in your tutorial or other piece of documentation.
- **Be descriptive:** Avoid using terms like "Conclusion" and "Introduction" due to their vagueness. Instead, make them specific and ensure they describe the section's content.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
- **Be descriptive:** Avoid using terms like "Conclusion" and "Introduction" due to their vagueness. Instead, make them specific and ensure they describe the section's content.
- **Be descriptive:** Avoid using terms like "Conclusion" and "Introduction" due to their vagueness. Instead, make them specific and ensure they describe the section's content.

This advice contradicts our own documentation outline approach. All our tutorials intentionally have headers such as Introduction, Summary, and Next steps. Please remove this line.

- **Include keywords:** Since sites like Google often use keywords to help people's online content appear on the web, Adding these terms effectively is helpful in reaching the tutorials or other pieces of content you create for our project to a wider audience.

#### Alt Text

Alt text are short descriptions of images used to help Google and people who use screen readers gain a better understanding of our tutorials and other pieces of content. To make them SEO-friendly, it's highly recommended to do the following:

- **Describe the image accurately**: Doing this would help our users understand how to use Asycapi in their work
- **Be concise**: While accuracy is important, avoid writing add every single detail about the image.
- **Use keywords strategically**: Avoid adding every single keyword to your image's alt text. It can overwhelm Google's search engine.

#### URLs

URLs are addresses to webpages and other forms of online content. In the context of SEO, they help make it easier for users to gain access content. To make them more SEO-friendly, use the following methods:

- **Make them short:** It'll make the links easier for users to comprehend and find the needed tutorial on our website
- **Use keywords**: Like alt text, effectively adding keywords in the URL would make it easier for Google to find them.
- **Avoid using special characters and spaces:** Characters like hyphens, numbers, ampersands(&), and spaces can make it difficult for the URL to quickly locate the content you're looking for on our site.
Loading