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: about this guide page #1291

Closed
wants to merge 35 commits into from
Closed
Changes from 29 commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
fb45217
new_workingfolder
thulieblack Feb 2, 2023
11ff9b2
introduction
thulieblack Feb 2, 2023
e1fdac2
writingguide
thulieblack Feb 2, 2023
ec6fc2b
update
thulieblack Feb 2, 2023
36935fe
update
thulieblack Feb 7, 2023
7a667ea
update
thulieblack Feb 7, 2023
13188f3
Merge branch 'asyncapi:master' into about_page
thulieblack Feb 7, 2023
6c96bf1
update
thulieblack Feb 7, 2023
1dc7570
Merge branch 'about_page' of https://github.com/thulieblack/website i…
thulieblack Feb 7, 2023
015dc47
update
thulieblack Feb 8, 2023
e852458
Merge branch 'master' into about_page
quetzalliwrites Feb 10, 2023
e36ffd4
Merge branch 'asyncapi:master' into about_page
thulieblack Feb 14, 2023
7f9a877
Merge branch 'master' into about_page
quetzalliwrites Feb 22, 2023
7442445
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
087db17
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
e42551d
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
f2aade0
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
c514e41
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
47088c9
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
1f1da6d
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
1ebde1b
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
328433e
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
43dc048
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
160aba8
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
5e73726
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
938b3b7
Update pages/community/styleguide/aboutguide.md
thulieblack Feb 22, 2023
b12d001
add_plagiarism
thulieblack Feb 22, 2023
806e929
update-plagiarism-text
thulieblack Feb 23, 2023
4edc426
Merge branch 'master' into about_page
quetzalliwrites Mar 7, 2023
e627d13
Merge branch 'master' into about_page
quetzalliwrites Mar 8, 2023
74c7e85
Merge branch 'asyncapi:master' into about_page
thulieblack Mar 9, 2023
21c158c
Rename pages/community/styleguide/aboutguide.md to pages/docs/communi…
thulieblack Mar 9, 2023
d25e754
Update aboutguide.md
thulieblack Mar 9, 2023
13192c0
Merge branch 'master' into about_page
quetzalliwrites Mar 10, 2023
f8ded38
Update pages/docs/community/styleguide/aboutguide.md
thulieblack Mar 10, 2023
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
48 changes: 48 additions & 0 deletions pages/community/styleguide/aboutguide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
## Introduction
Welcome to the AsyncAPI Style Guide. This page guides contributors on how to write, structure, and format content in documentation.

These guidelines help us maintain 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.

### Identify target audience
Before you begin planning and constructing your content, knowing who you are writing for and how the readers will benefit from your content is important.
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.

thulieblack marked this conversation as resolved.
Show resolved Hide resolved
### Plagiarism
Plagiarism can be defined as an act of using someone else's work as your own, without giving any acknowledgment or credit. Below are some scenarios that show plagiarism:

**Scenario 1**

Jane Doe is writing a docs page about APIs. She copies and pastes the content generated from ChatGPT word for word.

**Scenario 2**

John Doe is assigned a task to update graphics. He replicates some diagrams from an engineering book and doesn't give any credit to the author.

You can avoid plagiarism by:
- Paraphrasing and adding your own thoughts. For instance, in the first scenario, you can use content generated from ChatGPT for research and reference purposes.
- Quoting or citing your sources.
- Using plagiarism checker tools such as Grammarly, SmallSEOTools, and Plagiarism Detector.

### Follow writing principles
When writing 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 technical terms in simple and easy-to-understand words while considering your target audience. Additionally, keep your sentences short and sweet.
- **Concise** - It is crucial to be concise when conveying information. Removing redundancy caters to the reader's needs 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 documentation should be relatable. Always use an active voice instead of a passive tone when writing. Moreover, adding visual graphics and real-life examples helps the reader 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
It is crucial always to check grammar, punctuation, and spelling. View your work with a constructive eye while putting yourself in the reader's shoes. Thoroughly proofread your work and use writing tools such as Grammarly to polish up your work.

### Address feedback
A whole community of contributors is willing to support you via detailed feedback. All documentation pull requests go through several rewriting, editing, and proofreading rounds before they're ready to merge.