The Ruby on Rails guides use "please" when suggesting other resource to read or best practices to follow. For example: https://guides.rubyonrails.org/autoloading_and_reloading_constants.html
I've not seen this docs convention before. I certainly see the appeal for describing best practices: "your collaborators will appreciate it!"
miniblog.
Related Posts
I'm trying to decide the best voice for PL documentation.
Passive: "`let` can be used with destructuring."
Reader focused: "You can use `let` with destructuring."
Describing the PL: "FooLang supports destructuring with `let`."
Anyone have opinions or best practices?
Which programming languages are the closest to 'finished'? In other words, which are unlikely to expand core features or syntax such that best practices change.
C and Scheme seem to fit this, are there other languages?
I suspect every programming language eventually becomes dated.
As soon as you commit to 1.0, you will have design decisions that (with hindsight) are mistakes, and you can't fix them.
Design best practices change over time too. Immutability is a more common default now.