search

google / eng-practices

Google's Engineering Practices documentation
https://google.github.io/eng-practices/
Other
19.99k stars 1.95k forks source link

Readability: Define acronyms before use #22

Open austenwho opened 4 years ago

austenwho commented 4 years ago

It is already noted in the github repo that CL doesn't have any meaning outside of Google, and I'm glad that it is defined in the repo for those of us outside of the Google ecosystem.

I would like to make a suggestion that would solve this problem for people outside of Google (the documents have general appeal), as well as anyone within Google but new to the Google way of doing things.

1) Always define an acronym before using it. It is easy enough to say: "When starting to review a new change list (CL).." This way nobody has to feel like they're dumb for missing something so simple as what a CTLG is or a VA is, or make sure you STL that. It's frustrating when acronyms are used with no definition anywhere in sight. Did you miss it? Was it in that paragraph up top? Maybe it is defined in one of the other pages in the table of contents.... It is unnecessarily wasted time for the reader to hunt down what terms you are using.

2) Include a glossary.

Just my $0.02

I really like the documents otherwise. Lots of good lessons, looking forward to sharing them within my organization.

ninachen commented 4 years ago

Yes, agree. Presently, there's a terminology section here: https://github.com/google/eng-practices#terminology

but enough people have missed it that we could make this clearer.

veeara282 commented 4 years ago

It would also help to mention roughly equivalent terms used by most organizations, such as "pull request" and "merge request."

xdumaine commented 3 years ago

I'll add that I couldn't even find that terminology page. Having acronyms link to that page in a number of places would probably be sufficient.