Break up the design page into Features and Comparisons (#697)

* Break up the design page into Features and Comparisons

Signed-off-by: Carl Gieringer <78054+carlgieringer@users.noreply.github.com>

* PR edits

Signed-off-by: Carl Gieringer <78054+carlgieringer@users.noreply.github.com>

* Fix links

Signed-off-by: Carl Gieringer <78054+carlgieringer@users.noreply.github.com>

---------

Signed-off-by: Carl Gieringer <78054+carlgieringer@users.noreply.github.com>

howdju-docs/components/Feature.mdx

@@ -0,0 +1,21 @@
+import dynamic from "next/dynamic";
+/** A component for an unimplemented feature. */
+export function FeatureComponent({ issueId, children }) {
+  const issueLink = issueId ? <span>(
+    <a href={`https://github.com/Howdju/howdju/issues/${issueId}`}>
+      #{issueId}
+    </a>)</span> : null;
+  const abbrTitle = issueId ? `Future feature (#${issueId})` : "Future feature";
+  return (
+    <span>
+      <abbr title={abbrTitle}>{children}</abbr> {issueLink}
+    </span>
+  );
+}
+export const Feature = dynamic(
+  () => Promise.resolve(FeatureComponent),
+  {
+    ssr: false,
+    loading: () => <span>[enable JavaScript to see the feature]</span>,
+  }
+);

howdju-docs/pages/_meta.json

@@ -3,8 +3,11 @@
   "introduction": "",
   "design": "",
   "concepts": "",
+  "faq": "FAQ",
   "background": "",
   "organization": "",
+  "principles": "",
+  "policies": "",
   "community": {
     "title": "Community",
     "type": "menu",
@@ -34,21 +37,5 @@
         "newWindow": true
       }
     }
-  },
-  "principles": {
-    "title": "Principles",
-    "type": "page",
-    "href": "/principles"
-  },
-  "policies": "",
-  "policies_page": {
-    "title": "Policies",
-    "type": "page",
-    "href": "/policies"
-  },
-  "faq": {
-    "title": "FAQ",
-    "type": "page",
-    "href": "/faq"
   }
 }

howdju-docs/pages/concepts.mdx

@@ -23,17 +23,18 @@ Appearance -- apparition --> Proposition;
 Appearance -- location --> MediaExcerpt;
 ```
 
-- [Propositions] are the things that may or may not be true.
-- [Justifications] provide evidence for a proposition being true or false.
-- Justification have [Bases] that provide their support.
-- The two types of bases are PropositionCompounds and MediaExcerpts.
-- PropositionCompounds are an ordered list of Propositions and are similar to arguments from
+- [Propositions](/concepts/propositions) are the things that may or may not be true.
+- [Justifications](/concepts/justifications) provide evidence for a proposition being true or false.
+- Justification have bases that provide their support.
+- The two [types](/concepts/justifications#basis-types) of bases are PropositionCompounds and MediaExcerpts.
+- [PropositionCompounds](/concepts/justifications#propositioncompound-based-justifications) are
+  an ordered list of Propositions and are similar to arguments from
   propositional logic.
-- MediaExcerpts are references to a part of an external source.
+- [MediaExcerpts](/concepts/media-excerpts) are references to a part of an external source.
 
 Howdju also supports critique:
 
-- [Appearances] indicate that a Proposition appears in a Soruce.
+- [Appearances](/concepts/appearances) indicate that a Proposition appears in a Soruce.
 - An Appearance appears at a MediaExcerpt and the thing that appears is a Proposition.
 
 This structure allows a two-step critique of a source:

howdju-docs/pages/concepts/appearances.mdx

@@ -1,8 +1,16 @@
 # Appearances
 
-Appearances indicate that an entity appears at a MediaExcerpt. The appearing entity is called the
-"apparition". Howdju currently supports Proposition appearitions.
+import { Feature } from "../../components/Feature.mdx";
+
+Appearances indicate that an entity appears at a
+[MediaExcerpt](/concepts/media-excerpts). The appearing entity is called the
+"apparition".
+
+## Apparitions
+
+The types of apparations are:
 
 - PropositionAppearance: the speech represented by the MediaExcerpt is validly paraphrased by the
   appearing Proposition.
-- JustificationAppearance: the argument represented by the MediaExcerpt corresponds to the Justification.
+- <Feature issueId="690">JustificationAppearance</Feature>: the argument
+  represented by the MediaExcerpt corresponds to the Justification.

howdju-docs/pages/concepts/fact-checks.mdx

@@ -1,4 +1,4 @@
-# Fact Checks
+# FactChecks
 
 From an Appearance, you can click on the context menu for "User's fact-check". This
 will take you to a page which accepts sourceIds, urlIds, and userIds. The page will

howdju-docs/pages/concepts/justifications.mdx

@@ -1,15 +1,11 @@
 # Justifications
 
-A justification is when one thing makes another thing more likely to be valid or true. A
-justification represents a user’s intention to express or a belief in a relationship between a basis
-and an target. The basis is the starting point and the target is the conclusion arrived at by
-inference.
+import { Feature } from "../../components/Feature.mdx";
 
-Justifications represent a grounded implication of the truth of some target. One type of target is a
-proposition: the justification represents reasons for believing that the proposition is true or
-false. The basis may be external evidence or other propositions on the platform.
+A justification is something that makes another thing more likely either to be true or false.
 
-Justifications are the foundation of knowledge construction.
+Justifications are the foundation of knowledge construction because they represent deriving
+knowledge (the justification's target) based upon existing knowledge (the justification's basis.)
 
 ## Components
 
@@ -18,9 +14,32 @@ A Justification is technically a relation between a `basis` and a `target`. The
 which about which truth is being proven. The Justification's `polarity` determines the direction
 of the Justification is arguing for.
 
+## Target types
+
+Howdju currently supports one type of Justification, with others planned.
+
+### Proposition
+
+Proposition Justifications provide reasons for believing in the truth of a
+Proposition.
+
+### Appearance
+
+<Feature>Appearance Justifications</Feature> provide reasons for interpreting a
+[MediaExcerpt](/concepts/media-excerpts) as an appearance of its Apparition.
+
+### Relation
+
+<Feature>Relation Justifications</Feature> provide reasons for believing that a
+[Relation](/concepts/relations) holds between two other entities. The types of
+the entities and the meaning of the Relation depend on the specific type of
+Relation.
+
+## Basis types
+
 Justifications can have one of two bases: MediaExcerpts or PropositionCompounds.
 
-## MediaExcerpt-based Justifications
+### MediaExcerpt-based Justifications
 
 A MediaExcerpt-based Justification argues for or against the truth of its target based upon a
 reference to an external Source. MediaExcerpt-based Justifications are similar to when online
@@ -31,23 +50,27 @@ Howdju's MediaExcerpt-based Justifications improve on 'implication by hyperlink'
 recording the excerpt of the source that the Justification creator intended to provide the evidence.
 This explicitness speeds up readers review of the Justification.
 
-### MediaExcerpt-based Justifications vs. Appearances
+#### MediaExcerpt-based Justifications vs. Appearances
 
 It would have been possible to omit MediaExcerpt-based Justifications and to have only
 PropositionCompound-based justifications and Appearances. This approach would have required users to
 create very precisely worded Appearances so that they could then use them in their Justification.
 
 Howdju wanted to support people who were in a constructive mindset ("I trust this source and/or
 speaker, and therefore I believe it to imply the truth of the proposition") rather than forcing them
-into a critical mindset. This design decision is to allow these users the convenience of quickly
-adding the inferences into Howdju that they are observing as they read.
+into a critical mindset. See [the Epistemic Mode Hypothesis](/design/epistemic-mode-hypthesis) for
+background.
 
-Howdju is designed to facilitate criticism of these MediaExcerpt-based Justifications when users
-create Appearances at the MediaExcerpt and disprove the truth of those appearing Propositions.
+This design decision is to allow these users the convenience of quickly
+adding the inferences into Howdju that they are observing as they read. Do you sometimes experience
+an inferential leap while reading a source you trust? I.e. "if this is true, which it probably is,
+then it is good evidence for this other thing".
 
-Inferential leap.
+Howdju is designed to facilitate criticism of these MediaExcerpt-based Justifications when users
+create Appearances at the MediaExcerpt and <Feature issueId="694">disprove the truth of those
+appearing Propositions.</Feature>
 
-## PropositionCompound-based Justifications
+### PropositionCompound-based Justifications
 
 PropositionCompound-based justifications are like arguments in propositional logic. The Propositions
 in the compound (the "atoms") should, combined with the knowledge and judgment of the reader,
@@ -59,9 +82,82 @@ Justification:
 - Sufficient: taken together, the truth of the atoms proves the Justification
 - Necessary: removing any atom would defeat the inferential power of the Justification
 
+### Example-based Justifications
+
+<Feature issueId="168">Example-based justifications</Feature> are a special type
+of Justification handling the case where one or more examples of a target are given
+to imply the Justification's truth valence.
+
+- At most one example-based justification per target per polarity.
+- User's vote independently on the Justification and the Examples.
+
+A vote for an Example means "this is an example that contributes to my belief in
+the justification's polarity on the target." A vote against an example means "this
+is not an example that contributes to my belief in the justification's polarity on the target".
+That may mean that the user disagrees that the example is a valid example or just
+that it is not one that contributes to a conclusion.
+
+A vote for the justification means:
+
+- Positive: the examples I have voted on and/or seen convinced me to conclude
+  the justification's polarity about the target.
+- Negative: the examples I have voted on and/or seen have not convienced me to
+  conclude the justification's polarity about the target. The user may
+  optionally receive <Feature issueId="480">[notifications](/design/features#notifications)</Feature> for new examples.
+
+Example-based justifications are a sub-type of a contributory justification
+where the basis of the justification must be an example of the target.
+
+## Polarities
+
+A Justification's polarity indicates whether the basis makes the target true,
+false, or niether. Possibly Polarity values are:
+
+- Positive
+- Negative
+- <Feature issueId="33">Neutral</Feature>
+
+The meaning of a Polarity is target-specific:
+
+| Target | Positive Meaning | Neutral meaning | Negative meaning |
+| --- | --- | --- | --- |
+| Proposition | The proposition is true | The proposition is neither true nor false | The proposition is false |
+| Appearance | The apparition appears at the MediaExcerpt | N/A | The apparition does not appear at the Media Excerpt |
+| Relation | The relation holds | N/A | The relation does not hold |
+
+A Polarity is a permanent feature of a Justification. If a user wants to create
+an otherwise identical Justification with a different polarity, they must
+create a new Justification.
+
+## Strengths
+
+A Justification's <Feature issueId="692">Strength</Feature> indicates how
+thoroughly a Justification's basis proves the polarity about the target. Strengths
+have two possible values:
+
+- Conclusive: the justification's basis is sufficient to prove the polarity about
+  the target.
+- Contributory: the justification's basis makes the polarity more likely about
+  the target, but does not prove it.
+
+The creator of a Justification provides an initial Strength. Justification voters
+can vote with a non-default strength from a dropdown. The default strength presented
+to the user is a function of the user's inferred beliefs compared to the inferred
+beliefs of users who have voted on the Justification and the weight those voters
+selected.
+
 ## CounterJustifications
 
 A Justification can target another Justification and is called counter-Justification. The
 counter-Justification does not target the basis of the Justification directly. Instead, a
 counter-Justification defeats its target Justification in the particular context where the target
 Justificatcion appears.
+
+### Preferred-phrasing CounterJustification
+
+A CounterJustification focusing on a Proposition may have
+<Feature issueId="528">a special basis type of "preferred phrasing"</Feature>.
+The basis type indicates that while the countered justification may be effective
+on the current Proposition's phrasing, it loses strength against the proposed
+alternative Proposition. This feature enables redirecting attention to a
+steelman.

howdju-docs/pages/concepts/media-excerpts.mdx

@@ -1,25 +1,56 @@
-# Media Excerpts
+# MediaExcerpts
 
-Media Excerpts are references to a part of some media external to Howdju. They have local
-represenatations and remote locators:
+Media Excerpts are references to a part of some media external to Howdju. Their
+primary purpose is in [Appearances](/concepts/appearances) where they anchor
+a Howdju entity with a specific part of an external Source. They also have
+standalone utility for 'highlighting' a specific quote from a webpage or book.
 
-- Local representations allow users to assess the evidentiary quality of the excerpt without leaving Howdju.
-- Remote locators allow users to access the excerpt in its original context.
+MediaExcerpts unlock:
+
+- Analyzing the meaning of contextualized speech
+  - Debating what a speaker intended to mean
+  - Analyzing the truth of the underlying meaning
+- Semantic search and clustering
+  - Rediscover this context by searching for the meaning you interpreted to it.
+  - Find related thought appearing in different contexts
+
+A MediaExcerpt's components:
+
+- Quotation
+- URL(s)
+- Citation(s)
+- Speakers
+
+A MediaExcerpt's components serve two purposes:
+
+- Local representation: allows users to evaluate the evidentiary
+  quality of an excerpt without leaving Howdju
+- Remote location: allows users to find and view the excerpt in its original context.
+
+## Quotation
+
+The MediaExcerpt's quotation is the specific part of the source the user intended to reference.
+
+## URL
+
+The URL is the online location where the MediaExcerpt can be found.
 
 ## Citations
 
-Citations are remote locators that use bibliographic source citations to locate excerpts.
-They enable locating material which may not be available online or which the user may not know how
-to find online.
+Citations are bibliographic information. They enable MediaExcerpts of offline
+sources. Their information also provides context to users.
 
 Citations consist of a Source and an optional Pincite.
 
 ### Sources
 
-Sources are like bibliographic sources that would appear in a research paper. They have a textual
-description, which is MLA-like except that it omits the authors.
+Sources are bibliographic information similar to what someone would include in
+an academic paper when citing another authority. Howdju recommends an MLA-like
+style except omitting the authors since those correspond to [speakers](#speakers).
 
-Source's vs. Source containers
+- Title (the specific name of the article)
+- Publication (i.e. the name of the newspaper, journal, etc.)
+- Publication date
 
 ### Pincites
 
@@ -33,8 +64,6 @@ Examples of Pincites include:
 
 ## Speakers
 
-A MediaExcept may be associated with one or more speakers.
-
-### Persorgs
-
-Persorgs are something capable of making speech: a natural person or an organization.
+Users may associate one or more speakers with a MediaExcept to indicate the
+[Persorg(s)](/concepts/persorgs) that are directly responsible for the speech in
+the MediaExcerpt.

howdju-docs/pages/concepts/persorgs.md

@@ -0,0 +1,11 @@
+# Persorgs
+
+Persorgs are something capable of making speech: a natural person or an organization.
+
+Components:
+
+- Name
+- Known for: for natural persons, a disambiguator in the case of conflicting
+  names.
+- URLs: online locations to learn about the persorg or to further disambiguate
+  a person.

howdju-docs/pages/concepts/propositions.mdx

@@ -57,7 +57,7 @@ Correct: “The Burj Khalifa is the tallest structure in the world”
 Reason: is not a declarative clause.
 
 But: Howdju supports adding Propositions where the creator indicates that they question the truth of
-the Proposition. See [Questions](https://docs.howdju.com/concepts/questions).
+the Proposition. See [Questions](/concepts/questions).
 
 ### Dependent clause
 

howdju-docs/pages/concepts/relations.mdx

@@ -1,6 +1,8 @@
 # Relations
 
-Relations are assertions about two entities having a relationship. For example,
+import { Feature } from "../../components/Feature.mdx";
+
+<Feature>Relations</Feature> are assertions about two entities having a relationship. For example,
 the relation `PropositionEquivalence` asserts that two Propositions are equivalent. Both users and
 automated processes can create relations. Users can vote on the validity of relations.