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.

Sign up for GitHub

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

Jump to bottom

Docs: Additional guidance for creating an abstract #27302

Merged
merged 1 commit into from Aug 16, 2022
Merged

Docs: Additional guidance for creating an abstract #27302

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/src/main/asciidoc/doc-reference.adoc
View file
Open in desktop
Expand Up @@ -117,6 +117,7 @@ Start a new line at the end of each sentence, and split sentences themselves at
=== Abstracts (preamble)

For optimum findability, add a short description using user-oriented keywords to summarize the document's purpose, task, and intent in no more than three sentences.
Good abstracts also mention the benefits of following this content and avoid filler words, such as: "This document..", "This tutorial..", and "The following.."
Copy link

Choose a reason for hiding this comment

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

This is a good addition:)
I have 3 suggestions:

  • Please consider splitting this sentence into 2 shorter ones.
  • If you choose to follow the first recommendation, I suggest you swap the order of the 2nd and 3rd sentences (see example at the end of my comment.)
  • The use of the phrase this content is a bit ambiguous, because it might not be apparent what this is referring to. You might want to rephrase your sentence a little. For example:

Avoid self referential expressions and filler words, such as "This document..", "This tutorial..", and "The following.."
You should also mention what benefits users gain from reading the content that you are introducing.

Otherwise, LGTM! Nice work!


[IMPORTANT]
====
Expand Down