diff --git a/styleguide/aboutguide.md b/styleguide/aboutguide.md new file mode 100644 index 000000000..3af87bfe8 --- /dev/null +++ b/styleguide/aboutguide.md @@ -0,0 +1,53 @@ +--- +title: About Style Guide +description: This style guide page guides contributors on how to write documentation. +weight: 10 +--- + +## 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. + +### 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. +