APL Wiki:Content guidelines: Difference between revisions

From APL Wiki
Jump to navigation Jump to search
(→‎Verifiability: It's still better to rely on references than special verifiability rules)
(→‎What is APL?: Define an APL dialect, instead of refusing to define it)
(2 intermediate revisions by 2 users not shown)
Line 5: Line 5:
== What is APL? ==
== What is APL? ==


The APL Wiki is focused on APL, which is somewhat problematic because APL has no agreed-upon definition. We might say in a strict sense that APL, or "an APL", is a programming language that encodes [[Iverson notation]] in a text-based and machine-executable form, using the conventions established by the first such language to be broadly available, [[APL\360]]. However, because the APL Wiki should serve even remote corners of the APL world, we would like to take a broader definition of APL that also includes later developments that some people consider part of APL and some don't. Other definitions of APL or APL features might include:
The APL Wiki is focused on APL, which is somewhat problematic because APL has no agreed-upon definition. On the APL Wiki we define an [[:Category:APL dialects|APL dialect]], or "an APL", to be a programming language that encodes [[Iverson notation]] in a text-based and machine-executable form, using the syntax and symbols established by the first such language to be publically available, [[APL\360]]. This includes [[A+]], but not similar languages with different symbols like [[ELI]], [[J]], or [[BQN]]: these should be called "languages" rather than "dialects".
* The original [[IBM]] implementation of APL, [[APL\360]]
 
However, the APL Wiki does not merely document facts about APL dialects, but rather concepts that are important to users of APL. For this purpose it's important to discern not just whether a language is or isn't an APL dialect, but to what extent it can be considered a member of the APL family. Features that make a language APL-like might include:
* Features from the original [[IBM]] implementation of APL, [[APL\360]]
* [[Ken Iverson]]'s ideas of what APL should look like, realised in [[APL\360]], [[SHARP APL]], [[Rationalized APL]], [[A Dictionary of APL]], and [[J]]
* [[Ken Iverson]]'s ideas of what APL should look like, realised in [[APL\360]], [[SHARP APL]], [[Rationalized APL]], [[A Dictionary of APL]], and [[J]]
* A language which is typically called "APL" by the APL community
* Typically called "APL" by the APL community
* A language that uses the central concepts of Iverson's APL, like [[array]]s as the fundamental datatype, [[glyph]]s to represent [[primitive]]s, infix notation, and [[Evaluation order|right-to-left]] evaluation
* The central concepts of Iverson's APL, like [[array]]s as the fundamental datatype, [[glyph]]s to represent [[primitive function|primitive functions]] and [[primitive operator|operators]], infix notation, and [[Evaluation order|right-to-left]] evaluation
* Developments adopted by substantial portions of the community of APLers, such as the [[nested array model]].
* Developments adopted by substantial portions of the community of APLers, such as the [[nested array model]].
The APL Wiki takes no position on what can be called "APL", and this question is not important to its content (when in doubt, a controversial APL such as [[J]] may be called a "language" rather than an "APL" or "dialect"). Instead, an editor should consider the task of balancing how central a concept is to APL against its prominence and placement in the APL Wiki. See [[#Due weight]] below.
 
Other than the term "APL dialect", the APL Wiki doesn't assign any "APL score" or make any other direct statement of how APL-like a language is. Instead, an editor should consider the task of balancing how central a concept is to APL against its prominence and placement in the APL Wiki. See [[#Due weight]] below.


== Notability ==
== Notability ==
Line 51: Line 54:


In a dialect-specific article, you can assume (because you have told the reader) that the reader knows the page pertains to one APL only. This means it's acceptable to use terms like [[Disclose]] that are ambiguous in general but have only one meaning in the context of that APL, or terms like [[tradfn]] that many parts of the APL community don't use. Despite this, your primary aim should be to make the article useful for a general reader, who might never have heard of this APL. Use terminology which would be most readable for the wider APL community while remaining intelligible from the specific dialect's perspective. If there is no single term that fits, use a dialect-specific one but clarify by mentioning an identical or analogous term in parentheses.
In a dialect-specific article, you can assume (because you have told the reader) that the reader knows the page pertains to one APL only. This means it's acceptable to use terms like [[Disclose]] that are ambiguous in general but have only one meaning in the context of that APL, or terms like [[tradfn]] that many parts of the APL community don't use. Despite this, your primary aim should be to make the article useful for a general reader, who might never have heard of this APL. Use terminology which would be most readable for the wider APL community while remaining intelligible from the specific dialect's perspective. If there is no single term that fits, use a dialect-specific one but clarify by mentioning an identical or analogous term in parentheses.
The guidelines about dialect-specific terminology extend to pages about a group of dialects or languages if these share similar terminology (such as [[K]] derivatives). However, if an article pertains to multiple dialects with very different terminology, choose a single set of terminology in order to make the article consistent rather than switching between them. This may be either the most well-known of the dialects in question, or terminology from a mainstream APL or widely used across APLs.


For articles about a specific dialect, not just pertaining to it (such as [[A+]] or [[Dyalog APL versions]]), the emphasis is in the other direction: '''always give a language's preferred terminology on its own page''' when there is a clear preference. In order to make the page usable for general APL programmers, clarify terminology which is not obvious in parentheses: for example, the page on [[K]] lists the function "flip ([[Transpose]])".
For articles about a specific dialect, not just pertaining to it (such as [[A+]] or [[Dyalog APL versions]]), the emphasis is in the other direction: '''always give a language's preferred terminology on its own page''' when there is a clear preference. In order to make the page usable for general APL programmers, clarify terminology which is not obvious in parentheses: for example, the page on [[K]] lists the function "flip ([[Transpose]])".

Revision as of 13:47, 10 February 2021

APL Wiki's content policy is based on Wikipedia's. In general, Wikipedia's content policies and content guidelines are a good place to start if you're not sure what material belongs on the APL Wiki.

We do some things differently in order to support APL Wiki's focus on APL.

What is APL?

The APL Wiki is focused on APL, which is somewhat problematic because APL has no agreed-upon definition. On the APL Wiki we define an APL dialect, or "an APL", to be a programming language that encodes Iverson notation in a text-based and machine-executable form, using the syntax and symbols established by the first such language to be publically available, APL\360. This includes A+, but not similar languages with different symbols like ELI, J, or BQN: these should be called "languages" rather than "dialects".

However, the APL Wiki does not merely document facts about APL dialects, but rather concepts that are important to users of APL. For this purpose it's important to discern not just whether a language is or isn't an APL dialect, but to what extent it can be considered a member of the APL family. Features that make a language APL-like might include:

Other than the term "APL dialect", the APL Wiki doesn't assign any "APL score" or make any other direct statement of how APL-like a language is. Instead, an editor should consider the task of balancing how central a concept is to APL against its prominence and placement in the APL Wiki. See #Due weight below.

Notability

APL notability is not Wikipedia notability. While the APL Wiki adopts many of Wikipedia's notability guidelines, the concept of notability itself should not be shared between the two sites: then they would need to have the same content! While Wikipedia documents topics of general interest, the APL Wiki documents a specific interest: APL, and topics of interest to APLers.

Article notability

The APL Wiki is interested in documenting several things, which are considered inherently notable:

  • The APL language and array language family (e.g. Transpose)
  • Influences on APL's development (e.g. John Scholes)
  • The community of APL users (e.g. FinnAPL)
  • Applications of APL to interesting topics (not information about these applications but the applications themselves; e.g. Fast Fourier transform)

In general, being an APL user or knowing APL is not notable. To be interesting to an APLer, a user needs to have contributed to APL or the APL community in some way. So SimCorp, despite being notable enough for Wikipedia and a major user of APL, is probably not APL notable.

Because we consider some topics inherently notable, it is possible for a topic to be notable but not verifiable. If there is truly no verifiable information about a topic then it has no place on the APL Wiki, but our verifiability guidelines are more flexible than Wikipedia's and even material which is difficult to verify may be allowed. See #Verifiability.

Content notability

In general, only the APL-related aspects of a topic are notable. IBM has done a lot of things, but only its effects on APL or on APL developers belong in its APL Wiki article. Anything about IBM which is more generally notable by Wikipedia's standards should be on Wikipedia! This constraint is relaxed somewhat for articles on topics which are not found on Wikipedia. Keep the article focused on APL but it is fine to include expanded biographical or historical information for such topics. Relationships between two topics covered in the APL Wiki, even if they are not because of APL, should be included as well.

Due weight

Because the definition of APL is not rigorous (a particular language may be more or less APL-like), the notability guidelines above can be interpreted more strictly or more loosely. To determine whether content belongs on the APL Wiki at all, a loose interpretation is better. For determining how content is presented, however, editors should consider not just whether a topic is related to APL but how closely related, or central to APL, it is. Even a recent and niche development like Reverse Compose has a place in the Wiki, but most information about the primitive should remain on its own page and mentions on more central pages should be qualified in order to make it clear the primitive is not available in most APLs. In contrast, a topic like Outer Product can be mentioned anywhere, and omitting it from related articles like Inner Product or Each would be a mistake in emphasis.

To be central to the concept of APL, a language needs adherence to APL principles and prominence in terms of its user base or in the APL community. This is a modification of Wikipedia's due and undue weight policy, which relies on prominence alone. Adherence is measured roughly by the definitions in #What is APL?: languages that satisfy more of these definitions, and more closely, adhere better to the concept of APL. Prominence is determined by how many people use a language, how many of these are part of the APL community, and how strong an influence the language has had on the development of APL.

Keep in mind that many APL users are not very visible to the outside world and don't publish anything about their usage (especially after the decline of the APL conference). For example, you are unlikely to see recent material about APL2, but it is still widely used, and it's reasonable to think these users will look to the APL Wiki as a resource. As an editor you aren't expected to know every prominent language in order to contribute, but please think twice before removing material about a language you don't think is prominent. Evidence that the language is still in use might include major companies using it, active support forums, or significant development on the language indicating that it makes enough revenue to support this development. Significant historical use is also a sign, as usage of a particular APL rarely dies out quickly.

A language can be prominent even if it is very rarely used, or in extreme cases never implemented. This is the case for research languages that are important in developing features later picked up by more prominent APLs. For example, A Dictionary of APL, while only an incomplete description of how one APL might work, strongly influenced J and subsequently Dyalog APL. Extended Dyalog APL, used infrequently in the code golf community, has also had a significant influence on Dyalog APL. The APL Wiki should include information about these languages because they will likely continue to influence APL's direction in the future. However, it's also important to make sure that this information, which is of theoretical interest, doesn't interfere with practical content. It should generally be placed lower in articles or sections of articles, and the text should make it clear that this material probably doesn't apply to the reader's APL of choice, usually by specifying which language or languages it is taken from.

Dialect-specific pages

It is completely acceptable to have a page that applies to a single dialect of APL only. There are two circumstances in which this might make sense:

  • For encyclopedic articles, when a concept or feature is only present in one dialect.
  • For non-encyclopedic essays, when using a particular APL makes examples and discussion clearer or more concrete.

For articles, if a concept applies to multiple dialects, it would be inappropriate to write it from the perspective of a single dialect. However, there is no need to acquire an exhaustive knowledge of other APL dialects before writing an article. If you know another dialect has the feature you want to write about, but don't know how it might differ from the one you know about, simply indicate that any other dialects as part of a list of languages with the feature (probably in the introduction), and write the rest of the article about the dialect you know. Be sure to make it clear that you are writing only about a specific dialect, so that readers know the information might not apply to every APL. It is much more important to avoid incorrect information from making assumptions about an unfamiliar dialect than to make a particular article as general as possible. When writing an essay, such as a tutorial or example, the requirement to mention other dialects doesn't apply: simply make sure the reader knows which APL you are using.

In a dialect-specific article, you can assume (because you have told the reader) that the reader knows the page pertains to one APL only. This means it's acceptable to use terms like Disclose that are ambiguous in general but have only one meaning in the context of that APL, or terms like tradfn that many parts of the APL community don't use. Despite this, your primary aim should be to make the article useful for a general reader, who might never have heard of this APL. Use terminology which would be most readable for the wider APL community while remaining intelligible from the specific dialect's perspective. If there is no single term that fits, use a dialect-specific one but clarify by mentioning an identical or analogous term in parentheses.

The guidelines about dialect-specific terminology extend to pages about a group of dialects or languages if these share similar terminology (such as K derivatives). However, if an article pertains to multiple dialects with very different terminology, choose a single set of terminology in order to make the article consistent rather than switching between them. This may be either the most well-known of the dialects in question, or terminology from a mainstream APL or widely used across APLs.

For articles about a specific dialect, not just pertaining to it (such as A+ or Dyalog APL versions), the emphasis is in the other direction: always give a language's preferred terminology on its own page when there is a clear preference. In order to make the page usable for general APL programmers, clarify terminology which is not obvious in parentheses: for example, the page on K lists the function "flip (Transpose)".

Use the principle of due weight when deciding whether and how to link to a dialect-specific article elsewhere on the APL Wiki. If a concept is closely related to a better known one, it probably deserves a link, but the link should be in a less prominent position if the dialect with that concept is obscure. Less closely related concepts or non-obvious connections (for example, Raze is a left inverse of Partition and Partitioned Enclose on vectors) may or may not merit a link.

Verifiability

We make use of Wikipedia's definition verifiability, but expand the definition somewhat to allow some kinds of material that would otherwise remain undocumented. Even if these rules were used it can be helpful to the reader to have a secondary source that more directly states the information, so if you are aware of a traditional encyclopedic reference (other than the published documentation, which is too obvious to justify the clutter), consider adding a citation.

The results of evaluating an expression in any array language, even one which is not readily available to the public, are automatically considered verifiable. Please actually perform this evaluation if you are relying on this rule! Results are also considered verifiable if they may be clearly derived from the language's published documentation.

Mathematical statements about APL with proof are considered to be verifiable. If you derive a new relation between APL primitives, and can prove it to a capable APLer, then feel free to put it on the wiki. Make sure you are clear about exactly which functions you are using, including distinguising between variations on APL primitives and noting any modifications or restrictions need to be made for the proven statement to hold.