Skip to content

run stylecheck #191

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

Merged
merged 12 commits into from
Apr 4, 2025
Merged

run stylecheck #191

merged 12 commits into from
Apr 4, 2025

Conversation

bc-devrev
Copy link
Contributor

No description provided.

@bc-devrev bc-devrev added the stylecheck Revise markdown files according to DevRev style guidelines label Apr 2, 2025
Copy link
Contributor

github-actions bot commented Apr 2, 2025

Copy link
Contributor

github-actions bot commented Apr 2, 2025

@bc-devrev bc-devrev marked this pull request as ready for review April 3, 2025 18:28
@bc-devrev bc-devrev requested a review from a team as a code owner April 3, 2025 18:28
Copy link
Contributor

github-actions bot commented Apr 3, 2025

Comment on lines 21 to 26
- If the item consists of a single word, don't add end punctuation.
- If the item doesn't include a verb, don't add end punctuation.
- If the item is entirely in code font, don't add end punctuation.
- If the item is entirely link text or a document title, don't add end punctuation.
- Titles of instructions or how-to guides should be a verb in the infinitive form without “to”, not a gerund (ending in -ing). Titles of any other type of section should be noun phrases. No newline at end of file
- Titles of instructions or how-to guides should be a verb in the infinitive form without “to”, not a gerund (ending in -ing). Titles of any other type of section should be noun phrases.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Suggested change
- If the item consists of a single word, don't add end punctuation.
- If the item doesn't include a verb, don't add end punctuation.
- If the item is entirely in code font, don't add end punctuation.
- If the item is entirely link text or a document title, don't add end punctuation.
- Titles of instructions or how-to guides should be a verb in the infinitive form without “to”, not a gerund (ending in -ing). Titles of any other type of section should be noun phrases.
\ No newline at end of file
- Titles of instructions or how-to guides should be a verb in the infinitive form without “to”, not a gerund (ending in -ing). Titles of any other type of section should be noun phrases.
- If the item consists of a single word, don't add end punctuation
- If the item doesn't include a verb, don't add end punctuation
- If the item is entirely in code font, don't add end punctuation
- If the item is entirely link text or a document title, don't add end punctuation
- Titles of instructions or how-to guides should be a verb in the infinitive form without "to", not a gerund (ending in -ing). Titles of any other type of section should be noun phrases.

@bc-devrev
Copy link
Contributor Author

✨ Comment from AI reviewer ✨

Since this appears to be the style guide itself, there are relatively few issues to fix. However, I noticed a few items that could be improved for consistency with the rules:

  1. The second-level list items under "Instructions or how-to guides" weren't consistently using periods at the end of sentences.
  2. The parallel structure in the first bullet list could be improved.
  3. Added proper hyphenation for "two-level."

I made suggestions where possible but couldn't add them everywhere. My complete revision is below.

Full text
## Rules

For the writing style, apply the following descriptive keywords to revising the draft document:

- Writing style: authoritative, comprehensive, helpful
- Sentence structure: varied, complex, cohesive
- Vocabulary: consistent, technical
- Grammar and syntax: structured, flawless, articulate
- Description: clear, concise, informative
- Language: standard technical/professional US American English; not British, Indian, or other variants

There are also some very specific style rules that need to be followed:

- Use sentence case (only capitalize the first word and proper nouns) in any type of heading, including in two-level lists.
- Ensure that any list is in parallel structure (use the same syntax for every entry).
- Instructions or how-to guides:
    - They may use two levels; both should be ordered (numbered) lists, not unordered (bulleted) lists.
    - Instructions should be in imperative mood.
    - If there is a location or condition in a step, it should be at the front of the main clause, which must still be in imperative mood.
    - Steps should be more than a single "click"; combine steps if needed to make them more meaningful. If there is an outcome of the step stated, it should be part of the same step, not a new step.
- End each list item with a period or other appropriate sentence-ending punctuation, except in the following cases:
    - If the item consists of a single word, don't add end punctuation
    - If the item doesn't include a verb, don't add end punctuation
    - If the item is entirely in code font, don't add end punctuation
    - If the item is entirely link text or a document title, don't add end punctuation
- Titles of instructions or how-to guides should be a verb in the infinitive form without "to", not a gerund (ending in -ing). Titles of any other type of section should be noun phrases.
- Avoid future tense when describing the behavior of the product. Use simple present instead.

Copy link
Contributor

github-actions bot commented Apr 3, 2025

Copy link
Contributor

github-actions bot commented Apr 3, 2025

Copy link
Contributor

github-actions bot commented Apr 3, 2025

Copy link
Contributor

github-actions bot commented Apr 3, 2025

Copy link
Contributor

github-actions bot commented Apr 3, 2025

Copy link
Contributor

github-actions bot commented Apr 3, 2025

Copy link
Contributor

github-actions bot commented Apr 4, 2025

Copy link
Contributor

github-actions bot commented Apr 4, 2025

@bc-devrev bc-devrev merged commit 969736c into main Apr 4, 2025
4 checks passed
@bc-devrev bc-devrev deleted the bc/check-ISS-157878 branch April 4, 2025 16:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
stylecheck Revise markdown files according to DevRev style guidelines stylecheck-complete
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants