Proposed changes to PhySH should be submitted as Github issues. Before opening an issue please review the contribution gudelines below.
Urgent small and specific edits to PhySH will be adopted as quickly as possible, assuming they are approved. Proposals for larger-scale changes or less urgent changes will be considered through discipline-by-discipline reviews; please be patient as we work to accommodate all requests.
Contribution guidelines
Considerations for the different types of suggestions:
When recommending a new concept:
- Please consider if the concept you’re about to suggest is really needed. If a closely related concept already exists, would adding the new proposal as an alias suffice? Adding a new alias to an existing concept is preferred over adding a new concept.
- Consider whether a similar concept from another discipline might suffice - you can suggest that existing concept be added also to your discipline.
- A new concept may be needed where a significant body of work (dozens of papers per year, say) is associated with it, and not distinguished by any existing concept in PhySH.
- Please provide aliases (including acronyms) for any new term - we also encourage suggesting new aliases for existing concepts. Having commonly used variants as aliases will improve the ability to search for them.
- Please specify the discipline(s), facet(s), and hierarchies (parent concept(s)) where the new term should be added.
- Labels should be short and well-defined rather than expressions combining many different things (see below for more detailed guidelines on labels). For example if you’re considering proposing “Quantum dancing & skiing” please consider whether it can be meaningfully broken up into “Quantum dancing” and “Quantum skiing”, or perhaps even just one term with the other as an alias.
- Recommendations for more specific terms (narrower concepts) under existing broad concepts are welcome.
When recommending a label change:
- Concepts are identified by a unique code, not by the label (the term you usually see) so labels can be easily altered to fix typographical errors or to better describe the meaning. Recommendations to improve concept labels are welcome. See the “Guidelines for term labels” section below.
When recommending removing a concept:
- Deleting concepts can have a significant impact. All manuscripts tagged with the deleted concept may need to be re-tagged with a replacement, for example. With PhySH we generally “deprecate” concepts (make them less visible, without actually removing them from the system) so there is sufficient opportunity for deprecated concepts to be handled properly before they are removed completely.
- Recommendations to delete rarely-used or obsolete terms will be considered but will be reviewed carefully.
- Duplicated terms will be handled more expeditiously.
When recommending a structural change:
- Large-scale changes could have an even broader impact than deletions, depending on the nature of the change. Nevertheless there may be occasional good reasons for making such changes. Moving a concept from one parent to another, or from one facet to another, is relatively straightforward. However, if that concept is itself the parent of many others, it could have a broad impact. These suggestions will be reviewed carefully.
- An alternative to a larger-scale change may be just to link things together better. Recommendations for adding “related” links between concepts to assist with navigation are welcome.
Guidelines for term labels in PhySH
- Characters in preferred labels (the form displayed to users) should be from the Latin-1 alphabet (some accented letters allowed, but no Greek characters). No superscripts or other special formatting. ASCII transliterations (eg. Mössbauer -> Moessbauer) can be added as aliases. Aliases may also use characters outside Latin-1.
- Labels should be relatively short - 30 characters is a good upper limit.
- The language of all labels is English. We are not providing alternate language labels at this time.
- Labels should describe their concept, and not require sibling or parent context for interpretation (eg. “Other xxx” does not work for a label)
- Abbreviations or acronyms should be avoided in labels; common acronyms can be added as aliases.
- The first letter of the label will almost always be capitalized; the first letters of subsequent words should be lowercase unless they are proper nouns. The names of chemical elements should be spelled out in most cases rather than abbreviated (and therefore lowercase if not the first word).
- The word “and” should be replaced by “&” anywhere it is used (“and” generally is to be avoided as indicating more than one concept is involved)
- Hyphenation should follow the APS style (i.e. join words without a hyphen where possible). Common alternate hyphenations may be added as aliases.
- Words in labels should be separated by single spaces; there should be no leading or trailing spaces in terms. Newlines, tabs, and other spacing characters are not allowed in labels.
- The serial comma should be used for lists, eg. “Radio, microwave, & sub-mm astronomy”
- Terms are ordered alphabetically among siblings; altering labels to establish a preferred order is not recommended.
Guidelines on hierarchy and relations
- The hierarchy should logically conform to the “narrower/broader” meaning - narrower terms should be either subclasses, part of, or instances of their parents.
- Terms that seem related in other senses than “narrower/broader” can have associative relations (“related”) between them.