Writing Guide and Policies

Golden is on a mission to map and generate human knowledge in order to accelerate discovery and education. This is a writing guide for contributing on Golden.

Neutral point of view

All articles on Golden should accurately report facts and information about a topic in the most informative manner possible while maintaining a neutral tone. Avoid stating personal opinions, controversial or contested assertions, or unproven assertions as facts. Use an impartial tone which does not seek to pass judgement on the subject or to take sides or a viewpoint.

Give the most balanced and nuanced perspective based on the main consensus viewpoint of experts and scholars in the field as well as any well supported opposing arguments. Avoid giving extremely fringe or conspiracy a false equivalency by giving them undue weight in an article.

No marketing language

Marketing language does not belong on Golden. This is especially important for descriptions of companies, products, or anything which users have a financial stake in. Contributors should generally avoid language like “best”, “most efficient”, “easy to use“, etc as these are almost always qualitative and uninformative to the user. Descriptions like “first”, “fastest”, “cheapest”, should be avoided unless a citation which directly supports the language used is supplied.

Support claims using citations

Citations on Golden provide evidence and support for claims made on Golden. Any claim which could be challenged or is controversial should be cited. The primary metric by which controversial or challenged claims will be judged is based on the quality and content of cited sources. High quality sources include scholarly papers in academic journals or news articles from reputable sources which undergo rigorous review. More niche or less well known sources can also provide important information but should be analyzed with a more skeptical eye before use. Primary source information, such as information about a company from their own blog or from a contributor who has personal experience with the topic is also ok to use, however it should be identified as primary source and used sparingly or in concert with third party sources when possible. Citations also provide a valuable source for further reading.

Short articles break the ice

Even articles which start out with little information can improve over time and become high quality articles. However, articles should still strive for equal weight. Unbalanced topics which give undue weight to niche or fringe aspects of a topic may give readers an unrealistic perception of the consensus viewpoint. While articles may initially be fragmented when in early stages, over time it is important for articles to morph into comprehensive articles which give proper weight to all aspects and viewpoints of the article according to their importance. Information builds on itself and knowledge generation takes effort and time.

Future proof your work

Avoid phrasing that will go out of date quickly like “recently” or “just launched”, “working on”. For example, replace “Biotech Company recently developed a new technology for x-ray crystallography” with “Biotech Company developed a new technology for x-ray crystallography in 2018”. Phrasing that goes out of date quickly can often be replaced by more permanent statements tethered to specific points in time. Adopting this writing style avoids unnecessary editing upkeep from the community.

Some common mistakes to watch out for

  • Avoid promotion or marketing style language.
    • Example: “This company is the fastest, best source for custom DNA Oligos….”
  • Avoid speaking as yourself or for an organization.
    • Example: “I think this is a great topic...”
    • Example: “We provide solutions for machine learning and automation…”
  • Avoid giving advice directly to the reader.
    • Example: “You should read this paper to find out more...”
  • Avoid personal opinions.
    • Example: “The best way to be happy is to expand your mind...”
  • Avoid unstructured or random information that is covered in another topic.
  • Avoid publishing sentence fragments, drafts in progress, empty tables, or generally incomplete material.
  • Avoid commit messages unrelated to the changes you’ve made in the article. Our focus on the mission takes precedence over jokes, socializing or other activities.

Directly copying text

Golden public topics text are open under Creative Commons 4.0 BY-SA license with some additional terms applied, so text from similarly licensed sources can be copied as long as there is attribution through a citation or further reading. However, direct copying is discouraged. Pages that are a direct copy of another page don’t provide additional value to the Internet. Contributors should strive to use their skills and expertise to improve on, or supplement, any specific source with additional information or sources rather than just copying. There are valid use cases for repurposing creative commons licensed sources but ideally this will be optimized around the best way of explaining a topic.

Code of conduct

Always remember that other contributors are using Golden because they also want to share information and knowledge with the world and that we’re all working towards an important shared mission. Constructive and friendly communication when editing will help other contributors understand why you made the changes you did. For example, deleting or reverting incorrect information from the site is a valuable service to the community. However, without a thorough explanation of why the edit was made, other contributors may not understand why the edit was made. This will help avoid unnecessary editing back and forth or other miscommunications. Focus on constructive feedback and education of other contributors towards the policies.

Topic naming policy

1. Make sure the topic doesn’t already exist by another name

  • Search by most common usage first and then by less common usages.
  • Search for a version of the topic title using contractions or abbreviations.
  • Search for versions with parenthetical disambiguation.

2. Consider common usage

  • Titles should be as recognizable as possible and follow common usage.
    • Example: Bill Gates is preferred to “William Henry Gates III”.
  • A user should expect to find the article with their natural query instincts. Knowledge of specific naming conventions shouldn’t be a prerequisite for finding the right article.
  • Keep in mind that common usage differs in different parts of the world.
  • Abbreviations should only be used if they represent the most common usage.

3. Precision, but not too much

  • Titles should have enough precision to identify a unique topic but no superfluous details that will be explained within the article.
    • Example: Maryam Mirzakhani is preferred to “Maryam Mirzakhani, Iranian mathematician, professor, and Field Medal winner”.
    • Example: Alan Turing is preferred to “British mathematician and cryptographer Alan Turing”.

4. Disambiguation

  • Disambiguation is necessary when a title name could refer to multiple article entities.
  • Unambiguous usages should not have any parentheses.
  • Use parenthetical disambiguation to add a context or class to an article to distinguish it as accurately as possible.
    • Example: Plasma (blockchain) is prefered to “Plasma”. The blockchain scaling solution proposed by Joseph Poon and Vitalik Buterin is an alternate usage of Plasma and therefore should have parenthetical disambiguation.
  • Alternate terms or phrases which accurately and uniquely identify a topic are preferred to parenthetical disambiguation if possible.
    • Example: Plasma cell is preferred to “Plasma (cell)”.

5. Style

  • Capitalization conventions follow sentence case.
    • The first word of the title should be capitalized.
    • Subsequent words should not be capitalized unless they would be capitalized in standard prose i.e. proper nouns.
  • Use singular form unless the topic specifically refers to a group or the topic only exists in plural form
    • Example: Airplane is preferred to “Airplanes”.

Inevitably, exceptions to these rules will arise (capitalization: “eBay”, “uPort”). Contributors should deviate from these conventions when necessary in order to improve Golden’s map of human knowledge.

Article structure

Overview:

  • An abstract succinctly describing the key elements of the topic. Usually a couple of sentences are sufficient.
  • An introductory paragraph at the beginning of the overview body. The introduction expands on the abstract and gives a basic explanation of the topic.
  • A well organized body with appropriate section headings. Contributors should use their creativity and knowledge of the topic to create a structure which gives the reader a solid framework for understanding a topic. Often the history or background of a topic comes after the abstract, but there are no rules set in stone for how to organize an article.
  • Information rich tables which provide relevant and accurate data on the topic.

Timeline:

  • Each timeline element should have a succinct title, a full text description of the event, and ideally a citation which gives a source for the information. Citations can be reused for multiple timeline elements.

Capitalization

  • Capitalize names and proper nouns.
  • Capitalize the first word in a sentence.
  • Capitalize the first word of a quote.
  • Capitalize cities, countries, nations, languages, major time periods, days, months.
  • Don’t capitalize after a semi-colon or colon.
  • Use title case for most words in the title of a book, article, or most other titled works.
  • Use sentence case for article titles, section headings, table columns, article titles.

Abbreviations

Abbreviations are shortened or contracted forms of words. They are useful for shortening the length of long or cumbersome phrases. However, excessive abbreviations can confuse or interrupt the flow of reading without proper usage.

Always use the full phrase along with the abbreviation in the first instance of the phrase in an article. Do not invent your own abbreviations or use abbreviations not already in common usage. Unless unavoidable, saving space by using a rare or niche abbreviation is usually offset by the time wasted for the reader to locate the meaning of the abbreviation.

Tense

In the main prose, generally use the present tense unless the subject of the article is deceased, an event in the past, or an entity that no longer exists. In timelines, typically use the present tense. Example: “AlphaGo Zero defeats the previous chess champion AI Stockfish 8” is preferred to “AlphaGo Zero defeated the previous chess champion AI Stockfish 8”.

Punctuation

Punctuation on Golden should follow standard English grammar rules (multi language support will be coming in the future). Make sure to conclude all sentences with periods including the abstract of all articles. Do not use exclamation marks unless directly quoting from a source that uses exclamation points.

Anything we should change? Let us know at [email protected]