From fb452171815d6325a196e5d4bd62395be7407c83 Mon Sep 17 00:00:00 2001 From: thulieblack Date: Thu, 2 Feb 2023 10:35:23 +0200 Subject: [PATCH 01/15] new_workingfolder --- pages/community/styleguide/aboutguide.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 pages/community/styleguide/aboutguide.md diff --git a/pages/community/styleguide/aboutguide.md b/pages/community/styleguide/aboutguide.md new file mode 100644 index 000000000000..e69de29bb2d1 From 11ff9b20bf6226d965228808436506d5046d9fc5 Mon Sep 17 00:00:00 2001 From: thulieblack Date: Thu, 2 Feb 2023 11:01:11 +0200 Subject: [PATCH 02/15] introduction --- pages/community/styleguide/aboutguide.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pages/community/styleguide/aboutguide.md b/pages/community/styleguide/aboutguide.md index e69de29bb2d1..6fcb2460443b 100644 --- a/pages/community/styleguide/aboutguide.md +++ b/pages/community/styleguide/aboutguide.md @@ -0,0 +1,5 @@ +# AsyncAPI Style Guide + +## Introduction +Welcome to the AsyncAPI Style Guide. This page serves as a guideline to contributors on how the content/documentation should be written, structured, and formatted. + From e1fdac2374ad154ae49b8997004e53779b4eec80 Mon Sep 17 00:00:00 2001 From: thulieblack Date: Thu, 2 Feb 2023 11:38:56 +0200 Subject: [PATCH 03/15] writingguide --- pages/community/styleguide/aboutguide.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/pages/community/styleguide/aboutguide.md b/pages/community/styleguide/aboutguide.md index 6fcb2460443b..264ddae6356e 100644 --- a/pages/community/styleguide/aboutguide.md +++ b/pages/community/styleguide/aboutguide.md @@ -1,5 +1,9 @@ # AsyncAPI Style Guide ## Introduction -Welcome to the AsyncAPI Style Guide. This page serves as a guideline to contributors on how the content/documentation should be written, structured, and formatted. +Welcome to the AsyncAPI Style Guide. This page serves as a guideline to contributors on how to write, structure, and format content/documentation. + +These guidelines help us in maintaining language, tone, and voice throughout the website. It also makes it easier for multiple contributors to work together on a single doc while ensuring consistency, accuracy, and clarity. + +## Writing Guide From ec6fc2b8edf99285c7a1cc4a927cf2ecb79de7f2 Mon Sep 17 00:00:00 2001 From: thulieblack Date: Thu, 2 Feb 2023 11:41:34 +0200 Subject: [PATCH 04/15] update --- pages/community/styleguide/aboutguide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/community/styleguide/aboutguide.md b/pages/community/styleguide/aboutguide.md index 264ddae6356e..25d315f1a7f6 100644 --- a/pages/community/styleguide/aboutguide.md +++ b/pages/community/styleguide/aboutguide.md @@ -5,5 +5,5 @@ Welcome to the AsyncAPI Style Guide. This page serves as a guideline to contribu These guidelines help us in maintaining language, tone, and voice throughout the website. It also makes it easier for multiple contributors to work together on a single doc while ensuring consistency, accuracy, and clarity. -## Writing Guide +## Writing Style From 36935febec33b24d62408a6242edfef54df3acdc Mon Sep 17 00:00:00 2001 From: thulieblack Date: Tue, 7 Feb 2023 15:15:29 +0200 Subject: [PATCH 05/15] update --- pages/community/styleguide/aboutguide.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/pages/community/styleguide/aboutguide.md b/pages/community/styleguide/aboutguide.md index 25d315f1a7f6..000eac0535f5 100644 --- a/pages/community/styleguide/aboutguide.md +++ b/pages/community/styleguide/aboutguide.md @@ -6,4 +6,21 @@ Welcome to the AsyncAPI Style Guide. This page serves as a guideline to contribu These guidelines help us in maintaining language, tone, and voice throughout the website. It also makes it easier for multiple contributors to work together on a single doc while ensuring consistency, accuracy, and clarity. ## Writing Style +Below are some recommendations to consider when writing your pages. + +### Have your target audience in mind +Before you begin planning and constructing your content, it is important to know who you are writing for and how the readers will benefit from your content. +This will help you in strategizing and simplifying your writing process. + +### Research +Before creating your first draft, it is beneficial to research similar resources and use them as references. Avoid plagiarism or copying and pasting from other websites unless the content already exists on our site. + +### Follow the writing principles + + +### Prune and polish + +### Ask for feedback + + From 7a667ea7bc75b0952a615c6e5de29d4266e57ba0 Mon Sep 17 00:00:00 2001 From: thulieblack Date: Tue, 7 Feb 2023 16:09:28 +0200 Subject: [PATCH 06/15] update --- pages/community/styleguide/aboutguide.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/pages/community/styleguide/aboutguide.md b/pages/community/styleguide/aboutguide.md index 000eac0535f5..e88af7403991 100644 --- a/pages/community/styleguide/aboutguide.md +++ b/pages/community/styleguide/aboutguide.md @@ -16,6 +16,13 @@ This will help you in strategizing and simplifying your writing process. Before creating your first draft, it is beneficial to research similar resources and use them as references. Avoid plagiarism or copying and pasting from other websites unless the content already exists on our site. ### Follow the writing principles +When writing our content or documentation, we aim to achieve the following: +- **Clear** - It is very important that your writing is as clear as possible. Avoid using jargon or ambiguous words. +Explain any technical terms in simple and easy-to-understand words while considering your target audience. Additionally, keep your sentences short and sweet. +- **Concise** - When conveying information, it is crucial to be concise when writing content/documentation. This reduces redundancy and caters to the needs of the reader while providing value. +- **Consistent** - Maintaining consistency makes it easy for multiple collaborators to work together efficiently. This ensures professionalism while making it easy to implement updates and changes. +- **Friendly** - +- **Accurate** - ### Prune and polish From 6c96bf16295006fccb2ca8d22e546b50acf1a79e Mon Sep 17 00:00:00 2001 From: thulieblack Date: Tue, 7 Feb 2023 19:59:15 +0200 Subject: [PATCH 07/15] update --- pages/community/styleguide/aboutguide.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pages/community/styleguide/aboutguide.md b/pages/community/styleguide/aboutguide.md index e88af7403991..6c7086c0b175 100644 --- a/pages/community/styleguide/aboutguide.md +++ b/pages/community/styleguide/aboutguide.md @@ -19,10 +19,11 @@ Before creating your first draft, it is beneficial to research similar resources When writing our content or documentation, we aim to achieve the following: - **Clear** - It is very important that your writing is as clear as possible. Avoid using jargon or ambiguous words. Explain any technical terms in simple and easy-to-understand words while considering your target audience. Additionally, keep your sentences short and sweet. -- **Concise** - When conveying information, it is crucial to be concise when writing content/documentation. This reduces redundancy and caters to the needs of the reader while providing value. +- **Concise** - When conveying information, it is crucial to be concise. This reduces redundancy and caters to the needs of the reader while providing value. - **Consistent** - Maintaining consistency makes it easy for multiple collaborators to work together efficiently. This ensures professionalism while making it easy to implement updates and changes. -- **Friendly** - -- **Accurate** - +- **Friendly** - Your content/documentation should be relatable. Always use an active voice instead of a passive tone when writing. Moreover, adding some visual graphics and real-life examples helps the reader better understand the information more practically. + +- **Accurate** - Lastly, your content/documentation must be accurate and precise. The information provided should be well-researched, appropriate, and not misleading. Readers rely on our content/documentation to solve their needs while saving them time doing unnecessary research. ### Prune and polish From 015dc47be4e1ade09cf0bd8ce87f52b1667603cc Mon Sep 17 00:00:00 2001 From: thulieblack Date: Wed, 8 Feb 2023 18:12:16 +0200 Subject: [PATCH 08/15] update --- pages/community/styleguide/aboutguide.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pages/community/styleguide/aboutguide.md b/pages/community/styleguide/aboutguide.md index 6c7086c0b175..69db4755c47c 100644 --- a/pages/community/styleguide/aboutguide.md +++ b/pages/community/styleguide/aboutguide.md @@ -26,9 +26,10 @@ Explain any technical terms in simple and easy-to-understand words while conside - **Accurate** - Lastly, your content/documentation must be accurate and precise. The information provided should be well-researched, appropriate, and not misleading. Readers rely on our content/documentation to solve their needs while saving them time doing unnecessary research. -### Prune and polish +### Prune and polish +At this point, it is very important to check grammar, punctuation, and spelling. View your work with a constructive eye while putting yourself in the shoes of the reader. Thoroughly proofread your work and make use of tools such as Grammarly to help polish up your work. ### Ask for feedback - +There's a whole community of contributors who are willing to support you, so don't be shy to ask for feedback. You'll probably go through a lot of rounds of editing and proofreading before you can finally get your docs merged. From 8577f0be823a64ae0721d10f771f44bd09ade20d Mon Sep 17 00:00:00 2001 From: thulieblack Date: Thu, 9 Feb 2023 12:13:15 +0200 Subject: [PATCH 09/15] access_page --- pages/community/styleguide/accessibility.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 pages/community/styleguide/accessibility.md diff --git a/pages/community/styleguide/accessibility.md b/pages/community/styleguide/accessibility.md new file mode 100644 index 000000000000..55ffef6e32f5 --- /dev/null +++ b/pages/community/styleguide/accessibility.md @@ -0,0 +1 @@ +# Accessibility \ No newline at end of file From 936044ec62afaf4b4cbe5c7abc5ce849c9e9ff03 Mon Sep 17 00:00:00 2001 From: thulieblack Date: Mon, 13 Feb 2023 17:46:31 +0200 Subject: [PATCH 10/15] update_language --- pages/community/styleguide/accessibility.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/pages/community/styleguide/accessibility.md b/pages/community/styleguide/accessibility.md index 55ffef6e32f5..eb204fc74b1e 100644 --- a/pages/community/styleguide/accessibility.md +++ b/pages/community/styleguide/accessibility.md @@ -1 +1,16 @@ -# Accessibility \ No newline at end of file +# Accessibility + +At AsyncAPI, we strive to make our documentation/content inclusive, accessible, and unbiased to everyone. We encourage all contributors to have diversity and inclusivity in mind when writing. To ensure this, we have provided an overview of general guidelines to follow. + +## Language +- Be clear and concise when writing. Avoid the use of complex language, technical jargon, and verbose explanations. +- Keep paragraphs and sentences short, simple, and on point. +- Always maintain a uniform structure. Use descriptive headings and subheadings to make navigation easy. +- Avoid using camel case or any unnecessary fonts and formatting. +- Always have the reader in mind when writing. Use appropriate and approved terminologies when describing disabilities. + +## Text and Links + +## Images + +## Graphics and Colors \ No newline at end of file From 223da3d1de4cf795290fc72bea7a05ba20668074 Mon Sep 17 00:00:00 2001 From: thulieblack Date: Tue, 14 Feb 2023 11:59:14 +0200 Subject: [PATCH 11/15] add_multimeadia --- pages/community/styleguide/accessibility.md | 25 +++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/pages/community/styleguide/accessibility.md b/pages/community/styleguide/accessibility.md index eb204fc74b1e..3e01374ae643 100644 --- a/pages/community/styleguide/accessibility.md +++ b/pages/community/styleguide/accessibility.md @@ -6,11 +6,28 @@ At AsyncAPI, we strive to make our documentation/content inclusive, accessible, - Be clear and concise when writing. Avoid the use of complex language, technical jargon, and verbose explanations. - Keep paragraphs and sentences short, simple, and on point. - Always maintain a uniform structure. Use descriptive headings and subheadings to make navigation easy. +- Use inclusive language and always keep the reader in mind when writing. + + +## Text +- Use the appropriate heading hierarchy. H1 is used for the main heading while H2 to H6 are used for subsection headings. +- Properly align text for easy readability. - Avoid using camel case or any unnecessary fonts and formatting. -- Always have the reader in mind when writing. Use appropriate and approved terminologies when describing disabilities. +- Define acronyms or abbreviations and always spell out any signs or symbols. +- Structure your text in a uniform format. -## Text and Links +## Links +- Use descriptive and meaningful link text. For example, do not use phrases like *click here* or *follow this link*. +- Always use an external link icon if a link opens up in a new tab. +- Make sure your links or URLs are valid and redirect to the correct destination. -## Images +## Multimedia +- Alt text must be clear and descriptive. Not more than 50 characters. +- Always use text rather than images, unless necessary. +- Use SVG instead of PNG or JPEG. It retains quality. +- Provide transcripts and captions for video content. +- Make sure your captions can be translated into various languages. +- Avoid auto-playing media, always provide controls. -## Graphics and Colors \ No newline at end of file +## UI +- \ No newline at end of file From 94d9ff373778fb3d7d5d0eff4ecf68c5220d6df8 Mon Sep 17 00:00:00 2001 From: thulieblack Date: Tue, 14 Feb 2023 12:53:03 +0200 Subject: [PATCH 12/15] update-ui-sec --- pages/community/styleguide/accessibility.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/pages/community/styleguide/accessibility.md b/pages/community/styleguide/accessibility.md index 3e01374ae643..885d113d999e 100644 --- a/pages/community/styleguide/accessibility.md +++ b/pages/community/styleguide/accessibility.md @@ -4,7 +4,7 @@ At AsyncAPI, we strive to make our documentation/content inclusive, accessible, ## Language - Be clear and concise when writing. Avoid the use of complex language, technical jargon, and verbose explanations. -- Keep paragraphs and sentences short, simple, and on point. +- Keep paragraphs and sentences short, simple, and to the point. - Always maintain a uniform structure. Use descriptive headings and subheadings to make navigation easy. - Use inclusive language and always keep the reader in mind when writing. @@ -30,4 +30,7 @@ At AsyncAPI, we strive to make our documentation/content inclusive, accessible, - Avoid auto-playing media, always provide controls. ## UI -- \ No newline at end of file +- Use the correct terminologies for UI elements. +- Format tables correctly and keep the text within the grid. +- Use basic HTML for button elements. +- Add icons to describe a function. Use the aria-label attribute when unsure of the icon name. \ No newline at end of file From 96e1fded18f091eede1ce881ab1e852bd7a5f591 Mon Sep 17 00:00:00 2001 From: thulieblack Date: Thu, 23 Feb 2023 11:56:35 +0200 Subject: [PATCH 13/15] update --- pages/community/styleguide/accessibility.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pages/community/styleguide/accessibility.md b/pages/community/styleguide/accessibility.md index 885d113d999e..b9e9304d0ddc 100644 --- a/pages/community/styleguide/accessibility.md +++ b/pages/community/styleguide/accessibility.md @@ -1,3 +1,8 @@ +--- +title: Accessibility +weight: 10 +--- + # Accessibility At AsyncAPI, we strive to make our documentation/content inclusive, accessible, and unbiased to everyone. We encourage all contributors to have diversity and inclusivity in mind when writing. To ensure this, we have provided an overview of general guidelines to follow. @@ -17,7 +22,7 @@ At AsyncAPI, we strive to make our documentation/content inclusive, accessible, - Structure your text in a uniform format. ## Links -- Use descriptive and meaningful link text. For example, do not use phrases like *click here* or *follow this link*. +- Use descriptive and meaningful link text. For example, do not use phrases like *click here* or *follow this link* instead use *see*. - Always use an external link icon if a link opens up in a new tab. - Make sure your links or URLs are valid and redirect to the correct destination. From f440162dd097b66c99cafee4120085be35a17914 Mon Sep 17 00:00:00 2001 From: V Thulisile Sibanda <66913810+thulieblack@users.noreply.github.com> Date: Thu, 9 Mar 2023 20:42:02 +0200 Subject: [PATCH 14/15] Update --- pages/{ => docs}/community/styleguide/accessibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename pages/{ => docs}/community/styleguide/accessibility.md (98%) diff --git a/pages/community/styleguide/accessibility.md b/pages/docs/community/styleguide/accessibility.md similarity index 98% rename from pages/community/styleguide/accessibility.md rename to pages/docs/community/styleguide/accessibility.md index b9e9304d0ddc..3faf35bd3fc0 100644 --- a/pages/community/styleguide/accessibility.md +++ b/pages/docs/community/styleguide/accessibility.md @@ -38,4 +38,4 @@ At AsyncAPI, we strive to make our documentation/content inclusive, accessible, - Use the correct terminologies for UI elements. - Format tables correctly and keep the text within the grid. - Use basic HTML for button elements. -- Add icons to describe a function. Use the aria-label attribute when unsure of the icon name. \ No newline at end of file +- Add icons to describe a function. Use the aria-label attribute when unsure of the icon name. From 6d35a12e400e53b977cc93d41e832706a8519c75 Mon Sep 17 00:00:00 2001 From: V Thulisile Sibanda <66913810+thulieblack@users.noreply.github.com> Date: Thu, 9 Mar 2023 20:46:37 +0200 Subject: [PATCH 15/15] Delete aboutguide.md --- pages/community/styleguide/aboutguide.md | 35 ------------------------ 1 file changed, 35 deletions(-) delete mode 100644 pages/community/styleguide/aboutguide.md diff --git a/pages/community/styleguide/aboutguide.md b/pages/community/styleguide/aboutguide.md deleted file mode 100644 index 69db4755c47c..000000000000 --- a/pages/community/styleguide/aboutguide.md +++ /dev/null @@ -1,35 +0,0 @@ -# AsyncAPI Style Guide - -## Introduction -Welcome to the AsyncAPI Style Guide. This page serves as a guideline to contributors on how to write, structure, and format content/documentation. - -These guidelines help us in maintaining language, tone, and voice throughout the website. It also makes it easier for multiple contributors to work together on a single doc while ensuring consistency, accuracy, and clarity. - -## Writing Style -Below are some recommendations to consider when writing your pages. - -### Have your target audience in mind -Before you begin planning and constructing your content, it is important to know who you are writing for and how the readers will benefit from your content. -This will help you in strategizing and simplifying your writing process. - -### Research -Before creating your first draft, it is beneficial to research similar resources and use them as references. Avoid plagiarism or copying and pasting from other websites unless the content already exists on our site. - -### Follow the writing principles -When writing our content or documentation, we aim to achieve the following: -- **Clear** - It is very important that your writing is as clear as possible. Avoid using jargon or ambiguous words. -Explain any technical terms in simple and easy-to-understand words while considering your target audience. Additionally, keep your sentences short and sweet. -- **Concise** - When conveying information, it is crucial to be concise. This reduces redundancy and caters to the needs of the reader while providing value. -- **Consistent** - Maintaining consistency makes it easy for multiple collaborators to work together efficiently. This ensures professionalism while making it easy to implement updates and changes. -- **Friendly** - Your content/documentation should be relatable. Always use an active voice instead of a passive tone when writing. Moreover, adding some visual graphics and real-life examples helps the reader better understand the information more practically. - -- **Accurate** - Lastly, your content/documentation must be accurate and precise. The information provided should be well-researched, appropriate, and not misleading. Readers rely on our content/documentation to solve their needs while saving them time doing unnecessary research. - - -### Prune and polish -At this point, it is very important to check grammar, punctuation, and spelling. View your work with a constructive eye while putting yourself in the shoes of the reader. Thoroughly proofread your work and make use of tools such as Grammarly to help polish up your work. - -### Ask for feedback -There's a whole community of contributors who are willing to support you, so don't be shy to ask for feedback. You'll probably go through a lot of rounds of editing and proofreading before you can finally get your docs merged. - -