Improve API Documentation Guidelines [ci-skip] #45332

siaw23 · 2022-06-11T20:11:18Z

Summary

Other Information

jonathanhefner

👍

When you are happy with the changes, would you mind squashing the commits?

jonathanhefner · 2022-06-13T18:58:35Z

guides/source/api_documentation_guidelines.md

-Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?
+Documentation has to be concise. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?


Let's leave this as is.

Doesn't "concise" mean "brief but comprehensive"? 🤔 ...

To me this would read "Documentation has to be brief but comprehensive but comprehensive."

Sounds like unnecessary repetition to me. No?

In common usage, I find that "concise" emphasizes "brief" more than "comprehensive." Here we want to especially emphasize "comprehensive" ("Explore and document edge cases..."), so I think the current way is fine. But if it troubles you, we can change "concise" to "brief."

jonathanhefner · 2022-06-13T19:06:14Z

guides/source/api_documentation_guidelines.md


-The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be phenomenal.
+The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper names. It'd be phenominal if you took this tidbit into account in your next blog post or presentation.


When I read that last sentence, I imagine it is said with a wink. But other readers might not pick up on that (and I don't think we add emojis to guides 🤔), so perhaps we should just omit that sentence.

Suggested change

The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper names. It'd be phenominal if you took this tidbit into account in your next blog post or presentation.

The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper names.

Or we could go BIG.

Suggested change

The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper names. It'd be phenominal if you took this tidbit into account in your next blog post or presentation.

The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper names.

TIP: Using proper component names in your blog posts and presentations demonstrates that you are a Rails professional!

(I'm only half joking.)

I'll emphasise "should" instead like should.

jonathanhefner · 2022-06-13T19:06:51Z

guides/source/api_documentation_guidelines.md


-Spell names correctly: Arel, minitest, RSpec, HTML, MySQL, JavaScript, ERB. When in doubt, please have a look at some authoritative source like their official documentation.
+Spell names correctly: Arel, minitest, RSpec, HTML, MySQL, JavaScript, ERB, Hotwire. When in doubt, please have a look at some authoritative source like their official documentation.


Nice addition! 👍

jonathanhefner · 2022-06-13T19:08:02Z

guides/source/api_documentation_guidelines.md

@@ -283,7 +283,7 @@ In lists of options, parameters, etc. use a hyphen between the item and its desc
 # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+.
 ```

-The description starts in upper case and ends with a full stop-it's standard English.
+The description starts in upper case and ends with a full stop--it's standard English.


Since this will be rendered in a proportional (not monospace) font, let's use a true em dash:

Suggested change

The description starts in upper case and ends with a full stop--it's standard English.

The description starts in upper case and ends with a full stop—it's standard English.

jonathanhefner · 2022-06-13T20:09:11Z

guides/source/api_documentation_guidelines.md

-Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?
+Documentation has to be concise. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?


In common usage, I find that "concise" emphasizes "brief" more than "comprehensive." Here we want to especially emphasize "comprehensive" ("Explore and document edge cases..."), so I think the current way is fine. But if it troubles you, we can change "concise" to "brief."

jonathanhefner · 2022-06-13T20:24:19Z

guides/source/api_documentation_guidelines.md


-The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be phenomenal.
+The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation *should* consistently refer to Rails components by their proper names.


I'm unclear on the purpose of the asterisks...?

When I read that sentence aloud with vocal emphasis on "should", it sounds like I am saying "All Rails documentation probably consistently refers to Rails components by their proper names. (It should, but I don't know if it actually does.)"

Without the asterisks, it sounds like I am stating a fact, with the expectation that the fact will remain true. (i.e. I expect the audience to uphold the truth of that statement.)

siaw23 · 2022-06-13T22:15:31Z

Are we happy with the changes here? @jonathanhefner ;)

jonathanhefner · 2022-06-14T15:58:51Z

Looks great! Thank you, @siaw23! 😄

(Backported to 7-0-stable.)

…ment Improve API Documentation Guidelines [ci-skip] (cherry picked from commit 0adc234)

rails-bot bot added the docs label Jun 11, 2022

jonathanhefner reviewed Jun 13, 2022

View reviewed changes

Improve API Documentation Guidelines [ci-skip]

0809dd3

siaw23 requested a review from jonathanhefner June 13, 2022 22:12

jonathanhefner approved these changes Jun 14, 2022

View reviewed changes

jonathanhefner merged commit 0adc234 into rails:main Jun 14, 2022

jonathanhefner added a commit to jonathanhefner/rails that referenced this pull request Jun 25, 2022

Merge pull request rails#45332 from siaw23/api_doc_guidelines_improve…

1588fbb

…ment Improve API Documentation Guidelines [ci-skip] (cherry picked from commit 0adc234)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve API Documentation Guidelines [ci-skip] #45332

Improve API Documentation Guidelines [ci-skip] #45332

siaw23 commented Jun 11, 2022

jonathanhefner left a comment

jonathanhefner Jun 13, 2022

siaw23 Jun 13, 2022

jonathanhefner Jun 13, 2022

jonathanhefner Jun 13, 2022

siaw23 Jun 13, 2022

jonathanhefner Jun 13, 2022

jonathanhefner Jun 13, 2022

jonathanhefner Jun 13, 2022

jonathanhefner Jun 13, 2022

siaw23 commented Jun 13, 2022

jonathanhefner commented Jun 14, 2022 •

edited

		Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?
		Documentation has to be concise. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil?


		The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be phenomenal.
		The proper names of Rails components have a space in between the words, like "Active Support". `ActiveRecord` is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper names. It'd be phenominal if you took this tidbit into account in your next blog post or presentation.


		Spell names correctly: Arel, minitest, RSpec, HTML, MySQL, JavaScript, ERB. When in doubt, please have a look at some authoritative source like their official documentation.
		Spell names correctly: Arel, minitest, RSpec, HTML, MySQL, JavaScript, ERB, Hotwire. When in doubt, please have a look at some authoritative source like their official documentation.

	The description starts in upper case and ends with a full stop--it's standard English.
	The description starts in upper case and ends with a full stop—it's standard English.

Improve API Documentation Guidelines [ci-skip] #45332

Improve API Documentation Guidelines [ci-skip] #45332

Conversation

siaw23 commented Jun 11, 2022

Summary

Other Information

jonathanhefner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

siaw23 commented Jun 13, 2022

jonathanhefner commented Jun 14, 2022 • edited

jonathanhefner commented Jun 14, 2022 •

edited