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

Add a "Terminology" (or similar) section to the template #61

Open
nicopap opened this issue Jul 7, 2022 · 2 comments
Open

Add a "Terminology" (or similar) section to the template #61

nicopap opened this issue Jul 7, 2022 · 2 comments

Comments

@nicopap
Copy link

nicopap commented Jul 7, 2022

A terminology section would define jargon specific to an RFC.

A terminology helps RFC editing and reading:

  • Helps the author re-use the same terms to refer to identical concepts
  • Helps the author avoid mixing different ideas, on surface identical but not interchangeable
  • Helps the author identify the concepts they are using and structure their explanation with clearly defined concepts in mind
  • Helps the author limit how many different concepts they handle in the same RFC
  • The reader can refer to that section if they forgot the meaning of a particularly specialized term
  • The reader can pay closer attention to occurrence of terms specified in the terminology section
  • It makes RFCs more accessible, as it introduces context and jargon that non-experts may not know

This is different from the "User-facing explanation" concept sub-section, in that the terminology section is for the terms used in the RFC rather than just the ones introduced into the user-facing API.

Alternative names for this section are

  • Terminology
  • Jargon
  • syllabus
  • nomenclature
@alice-i-cecile
Copy link
Member

alice-i-cecile commented Jul 7, 2022

Strongly in favor of this. I've ended up including this in a couple of cases already.

I think that my favorite terms are: "Definitions", "Glossary" and "Terminology".

@djeedai
Copy link

djeedai commented Jul 16, 2022

Agreed, I started writing a RFC and this is the first thing I added. I vote for Terminology or Glossary.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants