Tag naming guidelines.
I've done a lot of work on tags lately and I'd like to share with the community some thoughts about the way tags should be named so that maybe it could become part of the FAQ and so hopefully lead to a more uniform tagging practice.
-
Acronyms should be spelled in all uppercase. This to avoid confusion with possible words (e.g.
ledvs.LED,canvs.CAN) and to make them stand out. -
The main tag for acronyms should be the acronym itself, not the spelled-out form. This latter should be added as a synonym, i.e. don't leave an acronym tag lacking the spelled-out form, do add it as a synonym. For example
LED(tag name) andlight-emitting-diode(synonym), not vice versa. This because almost always the acronym is more recognizable and it is what most people know about (some people don't even know what an acronym stands for). Moreover, it is shorter and this is good for the UI presentation. Spelled-out form(s) should always be added (as synonyms) to avoid another, separate tag to be created by another user. -
Otherwise tags should be all lowercase words separated by hyphens. This to ensure uniformity and wildly varying capitalization differences. This should be valid also for spelled-out acronyms, e.g.
LED, butlight-emitting-diode, notLight-Emitting-Diode. -
Exception: Only a person's name should be capitalized. This to convey the information that a word is not some technical term, but it is the name of a person. This can be important because people with different linguistic backgrounds can be misled. For example,
Darlington-pairand notdarlington-pair, because of Mr.Darlington not being some funny English word whose meaning eludes the reader. If some English native speaker is not convinced, try it out with some non-English name:Giacoletto-model,Dirac-delta,Popov-method,Routh-method,Ohm-law,Gauss-theorem(try to forget for a moment you maybe already know those people from your past studies and try to picture their name as a "plain" English word). -
The words should always be spelled out in singular form. This to avoid a mixup of singular and plural tags. E.g.
LEDand notLEDs,transistorand nottransistors,operational-amplifierand notoperational-amplifiers. This could be debatable, but IMO its the most sensible choice, since most terms make sense also in singular, but the contrary is not always true. There can be exceptions to this rule when the tag without the plural doesn't make sense, for exampleMaxwell-equationsand notMaxwell-equation(they are more than one), butShockley-equation(it's just that one). The same forKirchhoff-lawsand notKirchhoff-law. -
Saxon genitives should be suppressed. This to avoid entering tags with an apostrophe and, if someone entered the tag without the apostrophe, to confuse it with a plural form (see previous rule). E.g.
Kirchhoff-lawsand notKirchoffs-lawsorKirchoff's-laws,Maxwell-equationsand notMaxwells-equationsorMaxwell's-equations,Gauss-theoremand not ... what?Gausss-theorem?Gausses-theorem?Gauss'-theorem? Simply drop the genitive and be done with it, much less hassle and much more uniformity. -
No adjective-only tags, they can be very misleading. For example, what does
binary(actual tag) refer to? Binary numbers? Binary transmission? The same goes forserial(Communication? Interface? Bus? Serial number?),adjustable(Regulator? Parameter?),linear(Model? System? Amplifier? Regulator?),thermal(Protection? Resistance? Design?),resettable(System? Fuse? Protection?) orelectrical! -
No ambiguous tags. This is similar to the previous rule, but its applicable to nouns. Whereas adjective-only tags are almost always a problem, single-noun tags can be perfectly fine. However some nouns, often used as adjectives with other nouns, can have the same problems. For example:
flyback(Transformer? Power-supply?),high-speed(Design? Opamp? Signal? Communication? Bus?). And then there are nouns so general to be ambiguous in itselfzero(The number? The root of an equation? "Zero" as in "pole-zero diagram"? Some kind of reference level?).
The previous were essentially hard-and-fast rules that are easy to check without too much thinking, except for some corner cases. I devised them based on common sense, engineering practice and the premise that tags should help group questions with somewhat similar topics.
In other words, tags shouldn't be some kind of "keyword" systems that just helps in searching a question. They should convey "structure". Please correct me if I'm wrong on this and I have misunderstood the feature.
EDIT (numeric values in tags)
Because of the posts of Olin Lathrop and Lundin I realized my proposed guidelines missed something important: a rule about quantities. I propose the following to be added.
-
Tag names containing numeric values should be avoided if possible. That's because in general they don't convey particular structure to the questions. If a value is central to a set of questions it probably already has a name (e.g. π, ε0).
-
If a tag must contain a numeric value, it should contain the proper SI unit symbol, with correct capitalization as mandated by SI (e.g.
4mA,12V). The ASCII dot "." must be used as decimal separator (e.g.3.3V) and the ASCII hyphen "-" must be used if a range of values needs to be specified (e.g.4-20mA-loop). -
A tag containing a numeric value should also contain other words to better specify what the value refers to. E.g.
4-20mA-loop, not4-20mA;12V-system, not12V;3.3V-tolerant, not3.3V.
I'd like to avoid EE "jargon" values like 3V3 or 4R7 to represent 3.3V or 4.7Ω. This could be confusing for the newbie (remember, tags should avoid ambiguities and be as clear as possible).
As for SI prefix and units that can't be represented with basic ASCII characters, I think we should suspend our judgement until more information is gathered from tech staff.
Olin suggested to use HTML entities like μ for μ and Ω for Ω, which would be good in principle. However I feel there could be technical problems in some browsers and users may not be aware of what an HTML entity is. If someone experienced problems with entities they could bring more harm than good, with people trying to find workarounds that could mess-up tags.
For example, I think I read somewhere any Unicode "char" could be used in tags. So someone could use different code points to represent, say, Ω. In fact Unicode has Ω (U+03A9 GREEK CAPITAL LETTER OMEGA), but also (among others) 𝞨 (U+1D7A8 MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL OMEGA),
Ω (U+2126 OHM SIGN). Moreover, even HTML entities are not unique: there is also Ω Ω. So using entities could be like opening a big can of worms.
Note also that entities and Unicode chars might mess-up the sorting algorithm used to display the tag pages.
Unless we explicitly spell-out what entities are allowed and what's their use, we could have problems. In a way I would feel safer if we restricted the usable chars to (printable) ASCII alone.
So 1μF would be written as 1uF and 1MΩ would be written as 1Mohm [1], as ugly as that may be (at least it is guaranteed to work and it is predictable).
BTW, some standards also allow this explicitly, as mentioned in these Wikipedia pages:
-
"ohm" lowercase and singular, as is mandated by SI for the name of units, even if they are derived from people's name. ↩︎
3 answers
Additions:
-
Do not use company names in tags. Questions should be about specific products, not about companies. Furthermore, silicon companies merge/split and purchase each other all the time, so company tags will quickly become outdated.
For example, questions about STM32 should be tagged
STM32not "ST". Questions about AVR should be taggedAVR/ATMeganot "Atmel"/"Microchip". Questions about ARM cores should be tagged according to the specific coreCortex-M0etc, not "ARM" (way too broad). -
Do not use exact part numbers in tags. Use the family name or component type that the part belongs under.
A tag such as "STM32F302CC" is too specific - by all means do include the exact part number in the question (with a link to the datasheet) and schematics, but do not drag in specific sub-families and part numbers into the tag structure. In this case even "STM32F" or "STM32F3" is too specific and doesn't really add much meaningful information. There are thousands of microcontrollers out there and if we are to create a tag for each and every family, it will become messy.
Instead use the tag
STM32- the family name. Or you could usemicrocontrollerto just indicate the type of IC. Similarly, useRS232-transceiver, not "MAX232".A potentially valid exception to this rule is standard IC where multiple vendors exist, like 74HC parts.
1 comment thread
I agree with everything said. I didn't really consider until now that Codidact (unlike Someplace Else) supports case-sensitive tagging. So in addition, perhaps add a note regarding the following:
Capitalization of scientific units and quantities/prefixes should always be in accordance with the SI system (examples, more examples). Not following these standards when communicating with engineers will creature needless confusion.
Common typos:
- k means kilo, K means Kelvin.
- f means frequency, F means Farad.
- m means milli or meter, M means mega.
- a means acceleration, A means Ampere.
In case such units need to be present in tags, then the above conventions should be followed. Say that we for example think there should be a tag for 3V3 - the V must then be capitalized.
Other engineering conventions are that Greek letters may be replaced with Latin/English letters because of keyboard limitations. Examples:
- u is OK to use instead of µ,
- R is OK to use instead of Ω
(Related, I believe that editing posts solely to correct capitalization for units or prefixes should always be regarded as appropriate and substantial edits during edit review.)
In case decimal point is to be used, always use . and never , (common locale problem in northern European countries). And as seen above, it is also OK electrical engineering convention to use a unit instead of a decimal point in some places, like 3V3 instead of 3.3V, 6u8 instead of 6.8µF etc. Though mostly applicable to schematics or component prints more so than tags.
1 comment thread
Adding to what Lundin said (+1):
- s is seconds, S is siemens (1/Ω).
What we write here is inherently HTML. Greek characters like µ and Ω are defined as HTML entities, and can always be written with "µ" and "Ω", respectively. There is therefore no excuse here for using "u" instead of "µ", for example, regardless of what keyboard a user might have. See the Electrical Engineering site help page Formatting - special characters for more details.
1 comment thread
1 comment thread