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: new style guide - Grammar #1343

Closed
wants to merge 29 commits into from
Closed
Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
b4ed1b7
Added new styleguide - grammer.md
Arya-Gupta Feb 14, 2023
44ada9a
Merge branch 'asyncapi:master' into styleguide-grammar
Arya-Gupta Apr 4, 2023
0c8d149
Create _section.md
Arya-Gupta Apr 4, 2023
0084dac
Create _section.md
Arya-Gupta Apr 4, 2023
331843f
Create index.md
Arya-Gupta Apr 4, 2023
4511ec0
Create index.md
Arya-Gupta Apr 4, 2023
d9885fe
Merge branch 'asyncapi:master' into styleguide-grammar
Arya-Gupta Apr 4, 2023
81a0226
Merge branch 'asyncapi:master' into styleguide-grammar
Arya-Gupta Apr 11, 2023
9bb36cf
Update pages/docs/community/_section.md
Arya-Gupta Apr 11, 2023
7113f9c
Update pages/docs/community/styleguide/grammar.md
Arya-Gupta Apr 11, 2023
ce8f3d4
Delete _section.md
Arya-Gupta Apr 11, 2023
3683040
Delete index.md
Arya-Gupta Apr 11, 2023
4982603
Update pages/docs/community/index.md
Arya-Gupta Apr 12, 2023
8bebc96
Merge branch 'master' into styleguide-grammar
quetzalliwrites Jun 7, 2023
1be7703
Merge branch 'asyncapi:master' into styleguide-grammar
Arya-Gupta Jun 10, 2023
6aeec8d
Incorporated feedback into the style guide
Arya-Gupta Jun 10, 2023
00deace
Merge branch 'master' into styleguide-grammar
quetzalliwrites Jun 13, 2023
1bc3f11
fixing community content bucket weight
quetzalliwrites Jun 13, 2023
2599ff8
Another editorial round
quetzalliwrites Jun 13, 2023
59ccb0e
Merge branch 'asyncapi:master' into styleguide-grammar
Arya-Gupta Jun 13, 2023
fc6ac28
Added introduction to Grammar style guide
Arya-Gupta Jun 13, 2023
3dd3759
Merge branch 'styleguide-grammar' of https://github.com/Arya-Gupta/we…
Arya-Gupta Jun 13, 2023
2e97c7f
grammar improvements
quetzalliwrites Jun 16, 2023
43596d8
remove slack channel mention
quetzalliwrites Jun 16, 2023
769bfa3
sentence fix
quetzalliwrites Jun 16, 2023
d28c673
Merge branch 'master' into styleguide-grammar
Arya-Gupta Jun 16, 2023
ec1eadd
fixed directory structure
Arya-Gupta Jun 16, 2023
ee0a8fb
Merge branch 'styleguide-grammar' of https://github.com/Arya-Gupta/we…
Arya-Gupta Jun 16, 2023
cb41122
Merge branch 'asyncapi:master' into styleguide-grammar
Arya-Gupta Jun 30, 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
4 changes: 4 additions & 0 deletions pages/docs/community/_section.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: 'Community'
weight: 6
---
24 changes: 24 additions & 0 deletions pages/docs/community/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
title: Overview
weight: 2
---

Arya-Gupta marked this conversation as resolved.
Show resolved Hide resolved
## Community: Guidelines and resources around community.

Welcome to AsyncAPI **Community**! Our Community section documents the community guidelines and resources.

<Remember>

## Contribute to the AsyncAPI Community section
Code isn't the only way to contribute to OSS; Dev Docs are a **huge** help that benefit the entire OSS ecosystem. At AsyncAPI, we value Doc contributions as much as every other type of contribution. ❤️

To get started as a Docs contributor:
1. Familiarize yourself with our [project's Contribution Guide](https://github.com/asyncapi/community/blob/master/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/asyncapi/.github/blob/master/CODE_OF_CONDUCT.md).
2. Head over to our [AsyncAPI Docs Board](https://github.com/orgs/asyncapi/projects/12).
3. Pick an issue you would like to contribute to and leave a comment introducing yourself. This is also the perfect place to leave any questions you may have on how to get started.
4. If there is no work done in that Docs issue yet, feel free to open a PR and get started!

### Docs contributor questions
Do you have a documentation contributor question and you're wondering how to tag me into a GitHub discussion or PR? Never fear!

Tag me in your AsyncAPI Doc PRs or [GitHub Discussions](https://github.com/asyncapi/community/discussions/categories/docs) via my GitHub handle, [`alequetzalli`](https://github.com/alequetzalli) 🐙.
</Remember>
67 changes: 67 additions & 0 deletions pages/docs/community/styleguide/grammar.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
Arya-Gupta marked this conversation as resolved.
Show resolved Hide resolved
title: Grammar
description: This document provides grammar usage guidelines for clear and effective technical writing.
---
## Grammar

Copy link
Member

Choose a reason for hiding this comment

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

Please add a paragraph introducing this Grammar document.


## Abbreviations and acronyms

When you use an abbreviation or acronym for the first time, spell it out and include the shortest form in parentheses.

Abbreviations are meant to be used to save the reader’s time. They make your documentation look clean. However, using abbreviations may come with some downsides. Abbreviations add a layer of abstraction to text, which requires the reader to spend some mental energy to expand. Thus, it is best to add abbreviations in case of words that have been repeatedly used throughout your document. Abbreviations or acronyms, once defined in a document, should be used consistently to ensure clarity and avoid confusion for readers.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

Here are some examples of abbreviations:
- ‘Event-driven architecture’ can be abbreviated as ‘EDA’.
- ‘Producer Consumer Model’ can be abbreviated as ‘PCM’.

Here are some examples of acronyms:
- ‘Artificial Intelligence’ can be acronymized as ‘AI’.
- ‘Application Programming Interface’ can be acronymized as ‘API’.

## Active voice

Use active voice over passive voice whenever possible. Active voice makes writing easier to read and understand. When combined with short sentences, it makes it easy to convey an idea to the reader.

Passive: ‘The documentation is being read by Charlie.’
Active: ‘Charlie is reading the documentation.’

Passive: ‘APIs are leveraged by developers to save time while building software.’
Active: ‘Developers leverage APIs to save time while building software.’

Passive: ‘Clear instructions and explanations are provided for users by technical documentation.’
Active: ‘Technical documentation provides clear instructions and explanations for users.’

## Capitalization

Follow standard capitalization rules for American English. Avoid using unnecessary capitalization, and never capitalize for emphasis.

Here are some examples of when capitalization should be used:
- All proper nouns.
- The first letter of any sentence should be capitalized.
- Trademarked words that include capital letters.
- Names of programming languages or frameworks.
- References within a document.


## Spelling

Prefer American English over its counterparts.

A few examples:
- Use 'color' instead of 'colour'.
- Use 'analyze' instead of 'analyse'.
- Use 'skillful' instead of 'skilful'.

## Verb tense

Stick with the present tense wherever possible. However, in some cases, using the future tense might be unavoidable. The present tense is more appropriate when speaking about facts, while the future tense might be needed when referring to experiments or improvements that are yet to come.

The present tense is more appropriate when speaking about facts.
‘An AsyncAPI document is a file that defines and annotates the different components of a specific Event-Driven API.’

Future tense might be needed when referring to experiments or improvements that are yet to come.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
‘We will incorporate user feedback to address any problems in the documentation.’

Past tense is used while talking about events that have previously occurred:
‘Tutorials were added to the documentation as an entry point for new users.’