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 1 commit
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
Prev Previous commit
Next Next commit
docs: finished adding information about mobile and SEO-friendly techn…
…ical documentation
CBID2 committed Apr 3, 2024
commit 0f21cb8b627774132c53c88ec47d341469886dc9
26 changes: 22 additions & 4 deletions docs/styleguide/seo.md
Original file line number Diff line number Diff line change
@@ -79,9 +79,16 @@ Internal linking is the process of enclosing links to certain sections of a blog

### Examples of SEO-friendly anchor texts from Asyncapi's website

- "In this case, in your AsyncAPI file, you describe the `server`, and therefore the [Server Object](https://www.asyncapi.com/docs/reference/specification/latest#serverObject) holds information about the actual server, including its physical location."
- "JSON Schema Draft 07 is 100% compatible with AsyncAPI schemas. You can also use other standards to describe payload schema, such as [Avro](https://github.com/asyncapi/avro-schema-parser#usage)."
- "Furthermore, the [Pub/sub](/docs/tutorials/getting-started/event-driven-architectures#publishersubscriber) is appealing for IoT use cases due to two key features: support for flexible coupling between publishers/subscribers and inherent support for point-to-multipoint transmission."

### What are meta descriptions?

Meta descriptions are ["snippets of HTML code that are placed in a web page's header"](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates.
Meta descriptions are typically ["snippets of HTML code that are placed in a web page's header"](https://www.techtarget.com/whatis/definition/meta-description-tag). They appear under the title in the search results on Google and can significantly impact click-through rates.

>[!NOTE]
> In the case of Asyncapi's documentation, meta descriptions are written in YAML

#### Strategies for making SEO-friendly meta descriptions

@@ -101,13 +108,24 @@ description: In this tutorial, you'll learn how to generate code from your Async
In addition to having information that correlate to the content's topic, these meta descriptions are concise and contain keywords.

### Why mobile-friendliness important to technical documentation when making it SEO-friendly?
<!-- add explanation here -->

Whether it's on a tablet, smartphone, or computer, [people consume most online content on these devices](https://blog.google/products/marketingplatform/analytics/mobile-challenge-and-how-measure-it/). Also, making Asyncapi's content mobile-friendly would bring more users to the site as ["users are more likely to return to and have a high opinion of a product if it's website is mobile-friendly"](https://www.webfx.com/blog/web-design/user-experience-matters-marketing/). Lastly, mobile SEO-friendly technical documentation appears more in search results.

#### Strategies for making mobile and SEO-friendly content
<!-- add tips here -->

Here are some ways to make blog posts and documentation for Asyncapi's website mobile and SEO-friendly.

- **Use smaller images and videos**: Large images and videos can cause the documentation on Asyncapi's website to appear at slower rates, which create an unpleasant user-experience.

- **Use mobile-friendly font**: Some fonts can be hard to read on mobile devices, so it's crucial to picks font styles and sizes that can be adaptable to their screen sizes. It highly recommended to use styles like ["Arial, Tahoma, Verdana for headings and Times New Roman, Georgia, Bookman for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/) and sizes like ["14-16 point font for headings and 12-point for body text"](https://clickhelp.com/clickhelp-technical-writing-blog/choosing-fonts-for-technical-documentation/).
- **Give each topic its own page and/or section**: Consider putting a link to the next page or implementing internal links. It'll help users the project's docs and blog post have an easier time navigating the site.

>[!TIP]
> Consider using testing tools like [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) to ensure that the proposed blog post, tutorial, or other form of documentation for Asyncapi is mobile and SEO-friendly if quick results are needed.

### Examples of SEO and mobile-friendly content from Asyncapi's website
<!-- add list of examples -->

<!-- add examples here -->

### Why is quality important when making technical documentation that is SEO-friendly?
<!--add explaination here -->